Creating and Customizing Trackers

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:

1. Click on the Trackers tab,
2. 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:

• Permissions
• State Transitions (state transitions)
• Fields
• Escalation
• Notifications
• Service Desk

Delete a Tracker

Deleting a tracker will result in the loss of all tracker data.

To delete a tracker:

1. Click on the Trackers tab,
2. Click on the tracker's Customize link,
3. Click on General,
4. 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:

1. Field Access - for each status and role, set Read/Edit permissions for the issue fields, set default field values
2. 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.
3. Permissions - set Add/View/Edit/Close/Delete/ or Subscribe permissions for tracker issues, per role
4. Workflow Transitions - set permissions on workflow transitions, eg. an issue's transition from Verified to Resolved.
5. Choice Lists set choice-values for choice-fields
6. Notification - set notification options on the tracker.

To customize a tracker:

1. Click on the Trackers tab,
2. Click on a tracker,
3. Click on More icon,
4. click Customize

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 and template attributes.

You can also optionally associate an email address/inbox (see Email Integration: Sending Emails to codeBeamer for details) with the tracker, in order to allow submitting new issues via email.

Since CB-6.1 you can also hide a tracker or CMDB category from the Trackers or CMDB overview, by unchecking the Visible checkbox.
Hiding trackers/categories makes sense for system internal trackers, e.g. Time Tracking or Pull Request trackers, but you can also cleanup the Trackers and CMDB table by hiding trackers/categories that only contain stale information, that you want to keep for later references, but that you typically will not modify and more.

You can still show hidden trackers and categories by activating the "Show all" option in the Trackers and CMDB screen and you can also make a hidden tracker visible again.

Permissions - for Trackers and Issues

Click on the Permissionstab to edit permissions, by role, for

• issue Add
• issue add attachment
• issue add comment
• issue close
• issue delete
• issue edit
• issue subscribe
• issue history
• issue view attachment
• tracker mass edit
• tracker subscribe

Figure: Tracker permissions

State Transitions

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.

Figure: Tracker Customize -Field Access Permissions

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

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.

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

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.

Table fields

Using tracker configuration (fields tab) it is possible to create table fields.

To create a table field please follow the steps below:

1. Go to the tracker configuration.
2. Click on the field (4th) tab.
3. 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:

1. Click on the Trackers tab,
2. Click on Customize in the Actions tool-tip menu,
3. Click on the Fields tab
4. Click on Options link in the a Choice attribute's (Issue field's) row to edit
5. Click on the Add Option... link in the opening window to add new option
6. Double click on the option's name to edit the option attributes
7. Use Drag and Drop to reorder the options
8. Click on OK when finished,
9. 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.

Reference Fields

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
• Users
• Projects
• Trackers
• Work/Config Items
• Repositories

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:

Work/Config items

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:

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





Please note:
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:

1. Click on Trackers
2. Click on Customize
3. Click on Notification tab
4. Type use name to subscribers text field or click on the pencil icon at the end of the text field
5. Select users or/and roles
6. 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.

Audit Trail

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

Figure: Field Changes in Audit Trail