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.
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
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.
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. 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
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 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. 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.
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.
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 comments 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 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.
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).
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.
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.
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 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.
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.
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.
In the references menu you can:
create new referring items 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 New Referring Item 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 incoming and outgoing references.
You can access the references menu by clicking on the + icon in the blue bar front of the issue.
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 'c' icon above the center panel.
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 status of the issues
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
whether the issue has references or not
You can also combine the different kind of options.
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:
Work Item IDs: if checked then the node names in the tree will contain the issue ids. For example: " - 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
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.
To rate an issue with comments, the user must have the following permissions on the tracker:
Issue - Add Comment
Issue - Add Attachment
Issue - Edit Comment/Attachment - Any
Issue - Edit Comment/Attachment - Own
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. The filter is in the top-right corner of the middle panel.
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:
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.
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).
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:
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.
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.
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 for reused items
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.
You can only access review mode if you have Document Review license.
Review mode is a special mode of requirement document views. In review mode you cannot edit or move issues. You can however update their statuses with the transitions menu, add comments and rate the issues.
Review mode is easily accessed with an icon on the header: