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 certain trackers types. Please refer to Document View by Tracker Types for details. 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.

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 report query defined in the action bar control) 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

This functionality is available only in the document view of requirement trackers

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.

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. After dropping the test case you are presented with a popup like this:

In this popup you have two options:

• Verify Requirement with the original Test Case: 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.
• Make a copy...: This option copies the dropped Test Cases (after selecting this option you also have to select which tracker to copy to) and sets the Verifies field and the association on the copy issues. Note that if the tracker configuration of the source and the target Test Case Trackers is different you have to do some field mapping.

You can also select a Baseline during the linking process. If a Baseline is selected then the Depends associations that are created between the test cases and the Requirement will point to the baselined version of the Requirement

Linking requirements with incompatible Test Cases

There is one special case: on the test library there may appear Test Case trackers that are not compatible with the requirement tracker. This simply means that their Verifies field is configured such a way that it does not accepts items from the requirement tracker. These test cases still can be dropped to requirements but the only the Make a copy.. option is available for them on the overlay.

Configuring the test library

The list of test case trackers appearing on the test library is configurable. Just click on the gear icon above the tree to get the configuration dialog:

You can select whole projects (which is equivalent with selecting all the test case trackers from that project) and individual trackers. Note that you can select trackers that are not compatible with the requirement tracker (see the previous section).

Generating test cases

You can also generate a test case for a requirement. To do this just right click the + icon in the bar on the left of the requirement and select Generate Test Case. In this menu you're able to select to which test case tracker to generate the test 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 generating on a requirement that has children codeBeamer will ask if you'd like to generate recursively (for all children).

Working with releases

This functionality is available only in the document view of requirement trackers

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 update the target version of a requirement you can just move it directly inside the release tree from one release to an other (Note: from version 7.7 the original release is also kept in the release field).
• 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 to modify it, and it becomes editable.

As an alternative you can use the buttons in the bar to the left of the requirements.

By default, the WYSIWYG editor is selected, but this can be changed on user and system level.

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.

It is possible to edit issues in an overlay window since CB-9.0.0. The editing in overlay can be started by clicking on the 'Open in overlay' button in the WYSIWYG toolbar.

You can save your edited item from the overlay or also you can switch back to inline editable mode with the mode switcher icon (next to the close icon).

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.

An other way to add comments is using the bubble icon in the bar to the left of each issue. This will show a popup where you can write a new comment and see the comments written by others. The number in the bubble show how many comments there already are for the issue.

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:

The following subsections describe the four accordion sections of the properties panel.

Review statistics

This section is available only if the selected item has at least one review that is currently in progress (see Review Hub). The Review statistics section lists all the reviews that the current item is part of and also shows the votes of the reviewers.

Details

In this subsection you can view and edit the fields of the selected item. Of course only those fields are editable for which the user has the necessary permissions. If the user can not edit the item at all then a read only view of the fields is shown. The fields can be edited with in-place editing since CB-9.3.0.

Associations and References

These accordion panels list the downstream and upstream associations and references of the selected item and their suspected badges. You can also add new associations on this panel using the Add Association link.

Comments

Lists the comment of the selected item and you can also add new comments using the Add Comment link.

Associations and references

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 in the center panel:

You have three options:

• Link to this will create a reference between the two issues. The reference is created in the first available reference field of the dragged issue.
• Depends on will create an association of type Depends with the trigger suspected option set to true. The dependant end is the dropped issue.
• Related to will create an association of type Related between the two issues.

Not only you can drop issues from the left tree, but the same feature works also for the requirement library.

If you use Firefox, Internet Exporer 11+ or Chrome you can also drop issues between browser windows. Just grab an issue in the center panel in the first window and drop it to the center panel of the second window:

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:

• Open: opens the issue in a new tab
• Collapse Node, Expand Node: available only for the root element of the tree. Collapses or expands (respectively) the given node. It works recursively, that is, collapses/expands all descendant nodes of the selected one.
  • Note: Expand All control has been removed from User-Interface since codeBeamer 10.1.0.
• Rename: renames the tracker item
• 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.
• Delete: deletes the selected nodes (that is not necessary the same item where you clicked because there may be several selected nodes in the tree). Pops up a confirmation dialog. The selected items are 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.
• Cut: cuts the selected items
• 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.
• Show tree from this item: reloads the document view showing only the clicked item and its children (both in the tree and the center panel). You can access this menu item also on the table view.
• Go to Parent Item/Go to Root Item: after clicking the Show tree from this item menu only a subtree is shown in the document view. To show the subtree starting from the parent item right click the node and select Go to Parent Item. To get the whole tree again click Go to Root Item in the context menu.
• Export Selection (and their children) to Office: 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.
• Tag selection (and their children): adds tags to the selected items
• Mass Edit: starts the mass edit dialog for the selected items

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.

When you have more than one item selected in the tree the following menu items are available:

Transition menu

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

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 filling a form and page reload. However, if there's a mandatory field in the target status that is empty you'll get a popup where you can set all the mandatory fields.

References menu

In the references menu you can:

• create new downstream references for a requirement: the potential trackers are listed in th first section of the menu. These are the same tracker that you see when you click on the Create Downstream Reference menu on the item details page.
• generate new test cases for a requirement: this menu is only available if there are test case trackers that reference the current requirement tracker through their Verifies field (the default test case tracker of the projects is configured this way). Under this menu item you can choose the test case tracker in which you want to create the new test case.
• generate new risk for a requirement: this menu item is only available if there is a Risk field in the requirement tracker.
• view the downstream and upstream references.

You can access the references menu by clicking on the + icon in the blue bar front of the issue.

Compact Mode

With compact mode you can reduce the amount of space that the control icons take up. By default all the icons (transition, comment etc.) are shown on the left side of the center panel under each other. In compact mode however these icons are completely hidden under a grouping icon. To toggle compact mode click on the four headed arrow icon above the center panel.

Filtering

You can filter the document view using the report widget on the action bar. Just click on the report icon and start adding the report criteria:

When you defined the criteria just click on the Go button to see the filtered issue list.

There are filter options specific to document view:

• References: if the issue has suspected links or test cases with suspected links
• Average Rating: filters by the average rating of the issue

Under the "cone" icon you can access some predefined reports to make the filtering easier:

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 several options:

Their meanings:

• Work Item IDs: if checked then the node names in the tree will contain the issue ids. For example: "[7509] - Project Goal"
• 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 Work items 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).
• Only the open Work items: if checked only the open requirements are shown on document view.
• Add Review / Rating: if checked the rating functionality is available on document view. For more information about the ratings see this section
• Show Child Counts: if checked then the number of children is displayed for each node in the tree
• Synchronize the tree with the center panel: if this option is checked then moving the cursor above an item on the center panel will select the same issue in the left tree.
• Search In: by default the filter box above the left tree searches in both the contents and the summaries of the issues. In this section you can change this behaviour.

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 on the left of the issues. 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 using the report widget.

Reset ratings

If you're a project administrator you can reset the ratings to all issues on trackers. This means that all ratings from all users are deleted. This function is available under the more menu of the trackers:

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 "Create Baseline" menu item from the "more" menu and give a name and a description (optional) to the baseline in the popup window.

Viewing baselines

There is an 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 action menu bar turns blue. This makes it easy to recognise 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 from 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 bring up this popup:

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.

If the item that you want to copy have verifying test cases then the 'Copy the Test Cases' option is also available. After checking this option the test cases of the requirement will be copied to the selected test case tracker and the copies will be linked to the requirement copy. Eventually you might need to define the field mappings just like for the requirement.

Clicking on save 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.

Reviewing suspected links

If you create a reference or association between two items and check the 'Propagate suspected' option then whenever the target item changes you will be "notified" through the suspected badge.

Depending on the types of the items at the two ends of the relation there are two scenarios.

The linked items have different types

When the two items have different types clicking on the suspected bagde wil show a dialog like this:

This dialog shows the changes in the tracker item that triggered the suspected flag. For example: if you have two items (A and B), A depends on B and one user updated B. In this cases this dialog will show the changes made by the user on B.

By clicking the Clear Suspected button you can acknowledge the changes and remove the suspected badge until the item is updated again.

The linked items have the same type

When the two items have the same type clicking on the suspected badge will show a dialog like this:

The Changes tab shows the same information as the previous case: the changes made on the item that triggered the suspected flag.

The first tab shows the difference between the two linked items. Since they are of the same type we can copy the field changes from one to the other (even when they are not the copies of each other). Using the apply buttons you can select the changes that you want to apply to the source item.

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 triggered 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.

Permission note: if the user has the Issue - Suspected Merge tracker permission on the target tracker then he will be able to merge the changes even if he has no permission to the target item.

Document Edit View

Document Edit View is available on all trackers where:

• Document View is available
• the current user can edit items

This is a special view where the fields are inline editable and are presented in a table like form (just like in Microsoft Excel). These properties make it suitable for the fast editing of items.

The Document Edit View is accessible through an icon on the action menu bar:

Clicking on the icon will open the view with the default fields: by default shows the same columns as the table view.

Each field that you have access to is immediately editable. After a field was modified the left border of the row is set to red and all mandatory fields for the item are also marked with a reddish background:

You don't have to save the items one by one, you can edit as many as you want. After you finished your modifications just click the Save icon on the top toolbar to save them in one go.

Handling fields

As stated above the Document Edit View shows the same fields as the table view by default. One important difference is that the mandatory fields are always visible (even when they are missing on the table view). This is because you cannot save an item without setting its mandatory fields. The other difference is that the Description field is also always visible (you cannot remove it even from the context menu).

You can add new columns using the context menu of the column headers:

The columns can also be reordered by drag and drop.

After adding or removing columns or changing their order, the new column set can be stored, using the filter menu:

On this menu you can also select previously defined views. This reloads the page with the filters and the columns defined in the private view.

In Document Edit View, non-directly editable fields cannot be added as columns. This includes the Status field too as changing it involves using transitions.

To see an item status and manage transitions, use the icon in the left column:



Since Codebeamer 10.1 you are able to add shared fields to the table. For details, see: Reports.

Hotkeys

You can easily navigate between the cells of the Document Edit View with the following hotkeys:

• Tab/Alt+Right: next field of the current row or first field of the next row
• Shift+Tab/Alt+Left: previous field of the current row or last field of the previous row
• Alt+Up: same field of the previous row (one cell up)
• Alt+Down: same field of the next row (one cell down)