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, e.g. 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 the More icon,
4. Click on 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, 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 Breadcrumb 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 Breadcrumb 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.

You can also configure an icon for the tracker that will be used in wiki links, tree icons and in general everywhere where a tracker icon is shown. You can configure this using the Icon field. If you want to use the default icon instead of the one that you uploaded you can switch back to it using the Reset to default checkbox. Note that the icon must be a 32x32 pixel PNG image with transparent background. (This function is available from codebeamer Carmen.)

The tracker icon is inherited through templating and branching but you can overwrite it if you want. This means that when you create a new branch then the branch will have the same custom icon as the tracker you created it from.

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
• issue add attachment
• issue add comment
• issue close
• issue delete
• issue edit
• issue subscribe
• issue history
• issue view attachment
• tracker mass edit
• tracker subscribe
• branch merge
• item export

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

Field Access Permissions in State Transitions

The state transition window handles the transition between the source status and the target status of a tracker item.

If the user initiating the state transition has permission to edit a field in either the source status or the target status, that field is editable in the transition window. After you click Save in the transition window, Codebeamer assigns the target status to the item. This behavior ensures that the user who transitions the item can handle the mandatory fields.

For more information about transitioning items, see State Transitions and Transition menu.

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...
• 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
• under Extra actions... select Paste.

Fields - Custom Fields

Users can configure an arbitrary number of custom fields for a tracker. To add a new custom choice, reference or data field, use the commands from the dropdown menu at the bottom of the page.

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.

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 Spent Hours parent issue as the sum of the Spent Hours of the children issues, you can define this aggregation rule too. For more information please see Dynamic pick-list fields

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

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 the Options link in the 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 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 pop up.

Project Reference Fields

To define a reference field referring to projects (of specific Categories, where the users have specific permissions), choose Projects in the reference field configuration pop up.
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 pop up.
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 pop up.
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:

Limitations for the Status or Resolution Filter in Work/Config items

To allow a faster search and selection in a Work/Config items reference field, you can configure the field to display only the items that match a specific Status or Resolution value for a tracker or a group of work item types. Note that Codebeamer does not consider the filter set for Status or Resolution value in certain scenarios, such as:

• External integrations—The reference field is populated by external integrations, such as MS Excel import.
  • For example, the Excel Round-trip and Excel import features can populate a work or configuration reference field with an item in Closed status, even if the reference filter on the Codebeamer user interface allows only the selection of items in Open status.
• Status changes—The item selected in the reference field has changed its status after being set.

Repository Reference Fields

To define a reference field referring to Source Code Repositories, choose Repositories in the reference field configuration pop up.

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 codebeamer will pop up 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.:

Wiki Link/URL fields

Wiki Link/URL typed field can contain wiki links like "[ISSUE:1234]" or valid URLs like "[https://codebeamer.com]".

The link of Wiki Link/URL typed field always opens in new tab if it is an external link. Otherwise, it depends on the Preferences ► Open links in new browser tab setting.

This field can only contain valid URLs~. Sometimes users may want to add custom formatted URLs like "skype:user?call" or custom schemes like "doors://intland.com/doorsbridge": this is configurable on the Application Configuration page.

Wiki Link/URL editor able to set value as text or you can also set artifact from the Artifact Links overlay. Wiki Link/URL editor able to set the version/baseline of the selected artifact.

Token editing as text is possible with double clicking.

Date Fields

When creating or editing date of fields you have a few extra options compared to other type of fields. You can control which components (year, month, day and time) are shown when the field is rendered. With these options you can control the appearance of the date values on the item details page, on document view, report result page etc.

These options work well with any date format the user can select. Note that you cannot display the time only, you have to select the day component at least to be able to display the time as well.

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 the 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

Shared Fields

Since version 10.0.This page is about the reuse of Shared fields. To know more about administering the Shared Fields read this page: Shared Fields

Shared Fields are globally defined field types that you can use to group different fields from different trackers. Shared Fields can be used to refer to all those fields in a report.

When creating or editing a field you can add one or more Shared Fields to it. You can select only those Shared Fields that have the same type as the field itself:

On restriction here is that a Shared Field can be used only once in a tracker (that is only for one tracker field).

In the field list you can easily check which fields have Shared Fields set by hovering over the Shared Fields link:

You can use Shared Fields in report criteria. You can add a Shared Field just like any normal field. For example:

This example will match all items where a field has the textType Shared Fields and it is not empty. Note that you don't have to add the individual trackers to the report filters.

Using Shared Field names in calculated fields

It is possible to use the name of Shared Fields where unified expression language is used: Available from codebeamer 22.04 (Felicity).

• In Field Configuration of trackers:
  • Hide if,
  • Mandatory if,
  • Computed as,
• In conditions of State Transitions.

To use the names of the Shared Fields, write this expression into your calculation: sharedField("shared_field_name", TrackerItem(this, or detectedIn[0])); - this expression matches the field of the selected tracker item, where the name of the shared field is set to "shared_field_name".

Example expressions:

• sharedField("text_shared_field", detectedIn[0])
• sharedField("integer_shared_field", this) > 5

Creating Shared Fields

codebeamer 21.09 (Emma) and earlier

In codebeamer versions 21.09 (Emma) and earlier, the Manage Shared Fields link can be used to create new Shared Fields.

Manage Shared Fields ► Create Shared Field menu:

codebeamer 22.04 (Felicity)

Since codebeamer 22.04 (Felicity), the Create shared field link is added to New custom field... window, to let users create new Shared Fields without leaving the configuration page.

The Field Type is automatically populated based on the Type field's value. Once all the relevant details are added and saved, the new Shared Field appears in the Shared Field drop-down list.

See also:Shared Fields

Displaying Shared Fields while filtering on one or more Trackers

Since codebeamer 22.04. (FELICITY) release, the filtering drop-down list for Shared Fields on the UI has been refined.

The way Shared Fields are displayed in the filtering drop-down list (Reports, Trackers) is different when filtering on a single tracker than filtering on multiple trackers, to make filtering more clear-cut and user-friendly.

1. Filtering on a single Tracker

When filtering on a single Tracker (e.g. in Table View), the Shared Fields are not shown in a separate section of the filtering drop-down list, since those are identical with the fields of the Tracker.

The connected Shared Fields are displayed in parenthesis after the name of the relevant (custom) fields.

2. Filtering on multiple Trackers

By filtering on multiple Trackers (e.g. in Reports), the connected Shared Fields are

• displayed in a separate section of the filtering drop-down list, as before
  
  
• and are also shown in parenthesis after the name of the relevant (custom) fields.
  
  

See also: Reports