|Creating and Customizing Trackers #23424/HEAD / v15152|
Tags: CMDB, ITIL Report Trackers Workflow
Creating and Customizing Trackers
Table of Contents
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:
When a new tracker is created, it can:
The difference between copied and linked new trackers is:
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:
Delete a Tracker
Deleting a tracker will result in the loss of all tracker data.
To delete a tracker:
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:
To customize a tracker:
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
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.
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:
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.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
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 fieldsChanging 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:
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:
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.
Please see Field Access screen shot above, in the Field Access section.
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.
Trackers Reference Fields
To define a reference field referring to Issue trackers, choose Trackers in the reference field configuration pop up.
To define a reference field referring to Issues, choose Work/Config items in the reference field configuration pop up.
Besides the described filters, this function filters out all the Folder types, Information types and deleted items as well.
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 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 2: Contact language depending on country
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.
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.
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:
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.
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:
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).
Please note that Shared fields are only supported for Custom fields, currently there is no connection with built in fields and custom field business logic.
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).
To use the names of the Shared Fields, write this expression into your calculation: sharedField("shared_field_name", TrackerItem(this, or detectedIn)); - this expression matches the field of the selected tracker item, where the name of the shared field is set to "shared_field_name".
If the name of the Shared Field changes, the expressions referring the field are automatically updated. Shared Field name can be modified only if the Shared Field is not used in any tracker.
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
See also: Reports
codebeamer Knowledge Base
Services by Intland Software