This document is intended for project administrators, or those who need to change and extend the Tracker functionality. Tracker customization functions allow optimization of your work environment, whether in development, marketing, sales or people.
Project Administrators or users with sufficient permissions can create, customize and delete Trackers. Trackers can be customized to add, remove or change issue workflows, permissions, views, and the stored and displayed fields or attributes of the issues.
Permission to Customize Trackers
To give the entire set of users in the Project Admin role the permission required to customize a tracker, the Project Administrator can select the Member tab, then the Accounts and Roles Tab, then under the Project Admin role, select the tool-tip edit function. In the resulting chart, click the check-box for the Tracker-Admin function. This enables all users in the Project Admin role to customize the tracker.
For information on issue submission, editing and other user functions, please see Trackers
Create a Tracker
Adding trackers into projects can be manual, or can use other trackers as templates. Often the same or similar trackers are used in different projects. Template-based tracker creation allows easy creation of new trackers while reducing or eliminating manual tracker customizations.
Tracker creation by template copies all settings from the original tracker: permissions, layout, default values, approval and notifications settings. When the new tracker has been created, you can use copy/paste to copy tasks, bugs or requirements from the original tacker.
To add a new tracker:
Click on the Trackers tab,
Click on New Tracker,
When a new tracker is created, it can:
Link to a template to create a live connection to the template's tracker parameters
Copy from a template, receiving only once the configuration from the template tracker.
The difference between copied and linked new trackers is:
The copied tracker gets all the settings of the template tracker as they exist during creation. However the two trackers will subsequently become completely independent and changes in the original tracker will not affect the new tracker
The linked tracker is linked to the original-template tracker. This link causes all changes in the original-template tracker to be reflected in the linked-new tracker. It will always use the same settings as the original template.
To link to a template tracker simply select a tracker from the pull-down menu beside the Template Tracker menu item, in the New Tracker Add dialog. To select a non-linked copy of a template tracker, click on the checkbox that has the text: Do not inherit template configuration: Make a copy. If the tracker is copied, not linked, then the template setting on the newly created tracker will be None, as shown under the General tab. To create a tracker with no template, and no copy, select None for the template tracker field in the Add New Tracker dialog box.
Tracker customization allows configuration differences for specific Trackers to locally supersede the template's default configuration, a local delta for the tracker configuration. For example, Tracker CS-1000 Bugs could use Tracker CS-100 Bugs as a template, and inherit all its characteristics, except that the OP-SYS field in one would be replaced by 'Platform' in the other..
Inheritance and local deltas are available for the following tracker customization settings:
Deleting a tracker will result in the loss of all tracker data.
To delete a tracker:
Click on the Trackers tab,
Click on the tracker's Customize link,
Click on General,
Click on Delete.
Customize a Tracker
Edit field labels, types, their appearance, permissions, default values and sequences, or show/hide a field.
Customize trackers using the following steps:
Field Access - for each status and role, set Read/Edit permissions for the issue fields, set default field values
Field Properties - edit labels, types, appearances, default values and add new fields. For choice fields, enable using existing choices from Tracker Issues or Category items.
Permissions - set Add/View/Edit/Close/Delete/ or Subscribe permissions for tracker issues, per role
Workflow Transitions - set permissions on workflow transitions, eg. an issue's transition from Verified to Resolved.
Choice Lists set choice-values for choice-fields
Notification - set notification options on the tracker.
To customize a tracker:
Click on the Trackers tab,
Click on a tracker,
Click on More icon,
or, from the main Trackers list page, use the tool-tip customize on the particular Tracker of interest. The tracker customization is stored in addition to the link to the inherited template, for each Tracker, so that fields can be individualized for each particular tracker.
Figure: Customizing a Tracker
General - Edit Tracker Name and Description
The General tab is used for editing the tracker's name, description, key, template, and workflow attributes:
From codeBeamer 9.3.0, you can customize the color of the breadcrumb navigation field of a tracker. If you want to modify the color of the breadcrumb navigation field, select a color in the Color field. It is also possible to customize the icon of a tracker in the breadcrumb navigation field. To modify the icon, upload an image by selecting "Attach a file..." in the Icon field. The maximum size of the image that can be uploaded is 128x128 pixels.
When a branch is created for a tracker, the branch inherits the customized icon of the tracker. This means that the configuration window of the branch does not contain an Icon field and the option to upload an image.
As an option, you can associate an email address/inbox with the tracker, in order to allow submitting new issues via email. To associate an inbox with the tracker, select an inbox in the Inbox field. For more information, see section Email Integration: Sending Emails to codeBeamer.
To hide the tracker or CMDB category from the list of trackers or from the CMDB overview, check the Hidden checkbox in the Visibility field.
Hiding trackers/categories can be useful for system internal trackers, for example, Time Tracking or Pull Request trackers. You can also use this option to clean up the Trackers and CMDB table by hiding trackers/categories that contain old information which you want to keep for future references, but which you do not want to modify any more.
You can make hidden trackers and categories visible by activating the "Show all" option in the Trackers and CMDB screen. You can also make a hidden tracker visible again by unchecking the Hidden checkbox in the Visibility field.
From codeBeamer 9.4.0, it is possible to display parent/child items of tracker items by default. To display parent/child items of tracker items by default, select the Show Ancestor Items and/or Show Descendant Items option. If these options are selected, parent and child items will be displayed for tracker items in the Table View, Document View, and Document Edit View.
If ancestors/descendants are not displayed for the items of a specific tracker by default, and the Always Show Ancestor Items is also not selected in User Preferences (see Displaying Ancestor Items by Default in Document and Document Edit View), then instead of a tree view, you will see a simple list of tracker items on the left-hand side panel in the Document and Document Edit View of the tracker. It will not be possible to use the drag-and-drop function to change the order of the items on this panel or to include an item in another item as a child.
Permissions - for Trackers and Issues
Click on the Permissionstab to edit permissions, by role, for
issue add attachment
issue add comment
issue view attachment
tracker mass edit
Figure: Tracker permissions
When the issue is important, and must be carefully tracked, workflows enable process management. A simple and flexible process engine workflow is integrated into the Trackers to allow modeling of business process workflows. Trackers can be used with or without workflows. Trackers can "inherit" a workflow from other trackers or use their own workflows. Workflows can be customized. See State Transitions.
Define the workflow state diagram roles' transition permissions under the State Transitions tab. The Workflow Transitions define the transitions between states, and which roles have permission to enact each transition-type.
Figure: State Transitions
Field Access - Permissions
Edit the field access permissions for project members in the Fields tab in tracker customization. There is a permission column in the fields table, the permission can be edited by clicking on the field's permission cell content. Access permissions are a 3-dimensional matrix of permissions, with the axes of Roles, Issue Fields and Status. For every Status, there is table showing Field-Access permissions for each Role.
Each member's view or edit access to a field is defined for each status of the issue. Define a default value for a field, or make the field required, in the Field Access definitions.
Table: Field Access Defaults and Required Fields
Once you have selected this option, the default value property is enabled. The selected value is inserted to the fields on new Issue.
By selecting a required field the field must be entered on new issues, and on edit.
Issue Details Children and Associations
Issue hierarchies can be as deep as desired, using the child definitions in trackers. In issue lists, the children of an issue can be seen in the Summary column. The folder icon represents the set of children in one tracker, with a child-issue number and summary shown beside the folder, in the parent issue's Summary column. Navigate directly to the Children tab of the current (parent) issue by clicking on the directory icon, or navigate to the child issue, by clicking on its link. Similarly, navigate directly to associated issue(s) using the chain-link icon.
Figure: Issue List Issues with Associated or Child Issues
Anyone with edit permission on the Tracker can change the children and associations details of an issue.
Figure: Issues Details Screen Captures with Visible Children Tab
Figure: Issue Details Screen Capture with Visible Associations Tab
There can be different edit or view permissions tables for each status. The status is selected at the top of the table under the Field Access Tab.
When issues are copied or moved (using the Cut, Copy and Paste and Copy or Move to ... functions), the descendants (children) of the issues are also recursively copied or moved.
Issues can not only be moved between trackers but can also be copied or moved within the issue's hierarchy. It is possible to copy or move descendants of an issue to another tracker or to another issue within the same tracker. In the source issue list:
select the source issue's check-box,
select Extra actions... then
Copy, or select Copy to... then Put Selection to Clipboard in the resulting dialog box.
In the details of the target parent issue, select the Children tab, and
under Extra actions... select Paste.
Fields - Custom Fields
You can configure an arbitrary number of custom fields for a tracker. To add custom fields use the underlined commands at the bottom of the page to add a new custom choice or reference or data fields.
To add Custom Fields use the underlined commands at the bottom of the page Add_custom_choice or Add_custom_field to add a new custom choice or reference field or custom data field.
If you use a lot of custom defined fields, tables/lists of items/issues can become very wide. With Tracker Customization, you can exclude Fields from Table/List Views.
The List checkbox is used to configure which fields should be displayed (as table/list columns), and which should only appear on the details/editor screen.
Figure: Tracker Actions Customize Fields Tab
Using the Title field you can specify the column title to be displayed for the Label column. The column will resize based on the width of the column's title.
For a field to appear as table/list column, the field must be check-marked under the List column and the user must have at least “Read” permission for this field for the default status, specified under Field Access.
In per status configuration for custom fields, Default permissions are affecting the visibility in Report composer and in new item creation.
The Fields tab is used to define certain properties of a field. Under Field Properties the following are defined: field layout, sequence, type, label, title, minimums and maximums, whether it is listed, and hierarchical field dependencies (aggregation and distribution). Other properties of the field, such as default value, or the choice list, are defined under the Field Access and Choice Lists tabs.
Table: Customize the Field Properties
The sequence of the field on Edit, Submit and List forms. You can edit the sequences, and click on Renumber to save your changes.
Non-editable. Property name as used by CodeBeamer
Usually non-editable. New additional custom Property Type values can be text, integer, decimal, date, or a special Types choice and reference. Integer and decimal types can have minimum and maximum values.
Editable. The label of the field, may be different from the displayed Title.
Configure whether the field is displayed on the issue list or details.
Editable. Displayed Title of a field.
Box shown for Text Field: Number of the field's rows on the input page.
Box shown for Text Field: Number of the field's columns on the page.
The displayed field's width where: 1 means 1/3 of the page width, 2 means 1/2 the page width and 3 means full page width. See figure below, showing a customized tracker layout example.
When set, the field starts on the first-left position on a new row
When set, the checkbox means that, for example, mutliple 'assigned to' members can be selected.
Allows choices to refer to fields from other trackers, such as releases, members, etc. See Reference Fields, below.
Min. - Max.
Minimum and maximum values for integer and decimal fields
Parent Issue's Field Value depends on Child(ren)'s value(s)
Child Issue's Field value depends on the parent's value
Aggregate/Distribute: If you have parent/child hierarchies of configuration items or issues, you can now define dependencies between parent field values and the appropriate child field values (recursively). If, for example, you wish to ensure that a parent issue is not closed until all the child-issues (children) are closed, then this dependency can be managed using one of the distribution rules defined in this document. Similarly if you wish to define the parent issue's "Spent Hours" as the sum of the children's "Spent Hours" you can define this aggregation rule, too. For more information please see Dynamic pick-list fields
Changing the type of a tracker field is restricted. You can change the type of a text field to wiki text and vice versa, and the type of an integer field can be changed to decimal. Other field type changes are not allowed.
Figure: A Customized Tracker Layout Example.
Using tracker configuration (fields tab) it is possible to create table fields.
To create a table field please follow the steps below:
Go to the tracker configuration.
Click on the field (4th) tab.
Add a new table (find this option on the bottom of the page).
4.Fill in all the necessary information.
5. Add a new column by clicking on ‘more’ icon.
6. Go to the tracker where you added the table field and add new rows to the table by clicking on 'add new row...'.
The table field is ready to be further edited .
Choice Fields and Multiple Choice Fields
Using Choice Lists, tracker attributes or fields can be configured to allow selection from a list of choices. The list's items, order and default value can be defined.
To edit choice fields:
Click on the Trackers tab,
Click on Customize in the Actions tool-tip menu,
Click on the Fields tab
Click on Options link in the a Choice attribute's (Issue field's) row to edit
Click on the Add Option... link in the opening window to add new option
Double click on the option's name to edit the option attributes
Use Drag and Drop to reorder the options
Click on OK when finished,
Click on Save in Fields tab to store update modification when finished.
Figure: Choice List option dialog
Figure: Edit Choice option
The ID of each choice option must be unique only within this particular choice list. The ID will remain constant, even if choice values are copied between trackers/categories, or even if the label changes. Using an unmodifiable constant ID eases programmatic handling of items/issues, e.g. via the Remote API.
Tracker issues can contain reference fields, which are lookup and selection fields.
Reference fields are variants of choice fields, but contain dynamic, externally controlled references to fields in other trackers, instead of selections from a static set of local choice options.
Reference fields can be useful when release numbers, for example, are stored in one tracker, and other trackers in different projects must refer to the the list of release numbers.
If trackers need to be linked, such as a requirement tracker with a test tracker, reference fields can be used for a test tracker's references back to the list of requirements, to select the requirements that are relevant for the test.
Define reference fields using Tracker -> Customize -> Fields.
By clicking on the link in the Layout and Content column of a Choice field, you can show/define the reference field configuration, e.g. for the Release field in most trackers:
Reference fields' multiple values selection is configured in the Field Properties tab.
The multiple check-box appears automatically in the Field Properties for the field, after it is defined as a reference field.
Default values and access permissions for reference fields can be defined per status using the Field Access screen.
Please see Field Access screen shot above, in the Field Access section.
Since CB-6.0, reference fields can refer to the following types of objects:
Static choice list
A reference field can now also refer to objects from multiple sources, e.g. the Change Request Subject refers to Use Cases and/or Requirements:
User Reference Fields
To define a reference field referring to active users, choose Users in the reference field configuration popup.
Project Reference Fields
To define a reference field referring to projects (of specific Categories, where the users has specific permissions), choose Projects in the reference field configuration popup.
E.g. Reference to Projects of Category "Scrum" where current user has "Project Admin" permission:
If you do not specify a project Category, then projects of any category will match.
If you do not select any project permissions, then all projects visible to the current user will match.
Trackers Reference Fields
To define a reference field referring to Issue trackers, choose Trackers in the reference field configuration popup.
You must at least select one project, to refer to all trackers in these projects.
You can then further restrict the match to:
Specific Trackers in these projects by selecting them explicitly
Select all Trackers in these projects of a specific type
Select all Trackers in these projects where the user has specific permissions
E.g. Reference to Versions category in test project plus all tracker of Release type component and issue close permission:
To define a reference field referring to Issues, choose Work/Config items in the reference field configuration popup.
You must at least select one project, to refer to all issues in these projects.
You can then further restrict the match to:
Work/Config items from specific Trackers in these projects by selecting the trackers/categories explicitly
You can then optionally choose a view/filter to only include items/issues matching this filter/view.
Select all Tracker items in these projects of a specific type
Select all Tracker items in these projects where the user has specific permissions
E.g. Reference to all Use Cases and Requirements in the Demo project:
List of available filters contains a predefined set, and may include custom views as well.
The built in options are based on Meaning values of Status and Resolution fields:
Definitions of predefined filters are summarized in the following table:
no filtering at all
Status not Closed
Status is neither of Closed, Resolved, InProgress
Status is InProgress
Status is Resolved
Status is Closed
Status neither Closed nor Resolved
Status is Resolved, and Resolution is Successful
Status is Resolved, and Resolution is not Successful
Repository Reference Fields
To define a reference field referring to Source Code Repositories, choose Repositories in the reference field configuration popup.
You must at least select one project, to refer to all SCM Repositories in these projects.
E.g. Reference to all Subversion Repositories in the Demo project, where the current user has "Commit/Push" permission:
If you do not specify a repository type, then all repositories in the specified projects will match.
If you do not select any repository permissions, then all repositories visible to the current user will match.
If you are creating a new Tracker item or editing an existing one, e.g. Create a new Bug
then editable reference fields like "Detected Version" and "Target Version" will allow you to select possible fields values in two ways:
If you know parts of the value name or value description, simply type the first characters and codeBaemer will popup a menu with matching values
Click on the selector button of the field and codeBeamer will display a choice dialog with all possible field values.
If multiple selection is allowed, you can select any number of items, otherwise at most one.
Combined choice fields
Starting with release 7.1, codeBeamer also supports to combine static and dynamic choice fields, language and country fields and also member fields, via the new Depends On selector in the Layout and Content column on the Field Properties customization screen, in order to represent possible/allowed combinations (N-tuples, permutations) of values.
Example 1: Resolution depending on task status
Not all possible task resolutions make sense in every status. E.g. the resolutions "Fixed" or "Implemented" should only be available for tasks with status "Resolved".
You can configure, that Resolution depends on Status, via the Field Properties screen:
Make sure to first define all individual field choice values, in this case the Status and Resolution values, before defining the possible/allowed Status / Resolution field value combinations.
Define the possible/allowed Status / Resolution field value combinations, e.g.:
Please note the special placeholder Any, that allows to refer to all defined values of a field.
Example 2: Contact language depending on country
Another example for combining two fields, could be the Country and Language of Contacts:
Although there are no individual choice options to configure for Country and Language fields, the possible/allowed Country / Language value combinations, are still to be configured via the Choice Lists screen, e.g.:
Although the examples only show combinations of two fields, you can combine any number of fields (N-tuples), e.g. Status, Resolution and Follow Up, etc.
There can be also multiple fields depending on the same field, e.g Language depends on Country and also Currency depends on Country.
Subscribe Tracker Notifications
Subscribe notifications to the whole tracker result in e-mail notification when a new item is submitted to or modified in the tracker. Subscribe notifications can also be made on just a specific issue. See Trackers
To configure whole-Tracker notifications:
Click on Trackers
Click on Customize
Click on Notification tab
Type use name to subscribers text field or click on the pencil icon at the end of the text field
Select users or/and roles
Click on Save.
Figure: E-mail notification subscriptions on a tracker.
Figure: Subscriber chooser dialog
Adding time tracking to existing projects
Since release 6.0, CodeBeamer supports issue working time recording/tracking.
This optional feature (if licensed) will be available out of the box for new projects, but has to be added manually to existing projects, that have been created with older releases.
First you have to define a "Timekeeping" tracker for the project (Project -> Trackers -> New Tracker):
Generally you should only grant the Project Admin full permissions on the Timekeeping tracker (Tracker -> Customize -> Permissions):
All other roles should only have permission to add new recordings and to see their own recordings.
Next make sure that all trackers, where you want to record working time, have a "Spent Hours" field with "Sum/Total" value aggregation (Tracker -> Customize -> Field Properties):
Making "Spent Hours" formatted will display the value as "hh:mm" instead of a decimal.
Also grant appropriate field permissions to "Spent Hours" (Tracker -> Customize -> Field Access).
Issue trackers are associated with Time Recording trackers through Subject field (property name: subjects). It is defined in the field configuration of the Time Recording tracker which trackers are logging entries to that tracker. When creating a Time Recording tracker there are already a number of tracker types added to the Subject field. This scope can be limited or extended in the Work/Config items configuration.
The Audit Trail tab is available in tracker customization since CB-9.0.0. It displays the configuration change history of the customized tracker. Tracked changes include general tracker changes, field related changes and state transition changes.
The following audit information is available in the Audit Trail:
Tracker Changes - Customization changes which were done on the General tab
Field Changes - Fields configuration changes
Workflow Changes - Customization changes which were done to the state transitions
Transition Diagrams - State transition diagrams for each baseline versions and for the head revision
Permissions - Permission configuration listed by roles
Permission changes - Lists the field and tracker permission changes over time