Project Health Report
The Project Health Report is a validation tool for Codebeamer project administrators. It analyzes the project configuration and identifies invalid references, inactive dependencies, and structural inconsistencies that can affect export, deployment, or migration. The tool generates a CSV report that lists the detected issues for review and remediation.
Running the Project Health Report provides the following benefits:
• Prevents deployment failures by exposing configuration inconsistencies that block export or deployment.
• Detects broken references that result from deletion or refactoring activities.
• Verifies the consistency of the dependencies before migrating projects between environments.
• Identifies invalid workflows, formulas, and references that affect project behavior.
• Confirms that projects, templates, and deployment packages meet export requirements.
Generating and Preparing a Project Health Report
To use the Project Health Report, follow these steps:
1. Ensure that you meet all the prerequisites described in Prerequisites.
2. As a project administrator, navigate to the project that you want to validate.
3. Click the Admin tab.
4. Click Get project health report. The report is generated and downloaded automatically without using a background job.
 |
The Get project health report link appears only if you have the Project Admin project role for that project.
|
5. Save healthReport_[<project-ID>]-<project-name>.csv to your local system.
6. Open the file in Microsoft Excel to review the reported issues.
 |
For improved readability and analysis, convert the comma-separated values into Excel columns.
|
Understanding the Project Health Report and Identifying Validation Issues
The report has the following default columns:
|
Column
|
Description
|
|---|---|
|
Description
|
Explains the invalid reference and includes the full location path.
Example: An invalid reference [Tracker-59528] found in the field reference filter in [Project-21] Intland Software's Default Template 3 >> [Tracker-40245] User Stories >> [Field-17] Requirements >> [ReferenceFilter-40245] null.
|
|
Reference
|
Identifies the broken target reference in <entity-type-ID>-<entity-ID> format. When the target entity is missing, this column is empty.
Example: 3-59528, which represents Tracker-59528.
The entity type ID mappings are as follows:
• 1 = USER_TYPE
• 2 = PROJECT_TYPE
• 3 = TRACKER_TYPE
• 5 = ARTIFACT_TYPE
• 9 = TRACKER_ITEM_TYPE
• 13 = ROLE_TYPE
• 18 = REPOSITORY_TYPE
• 20 = PROJECT_ROLE_TYPE
• 22 = GLOBAL_TYPE_TYPE
• 24 = STREAM_BASELINE_TYPE
|
|
Path
|
Shows the location of the issue in the project as a path of entity IDs.
Example: 2-21/3-40245/17/40245, which represents Project-21, Tracker-40245, Field-17, and ReferenceFilter-40245.
|
|
Descriptor
|
Indicates the attribute type from which the broken reference originates.
Example: QUERY.
|
|
Reason
|
Specifies the error category.
Examples: DELETED_REFERENCE, INVALID_QUERY, INVALID_COMPUTED_FORMULA.
|
|
|
If the project has no validation errors, the rows under the default columns are empty.
|
The report scans the project to identify the following validation issues:
|
Reason
|
Description
|
|---|---|
|
DELETED_REFERENCE
|
References to entities that have been permanently deleted from the system, such as fields, role permissions, members, icons, homepages, project categories, template trackers, shared global types, service desk images, escalation listeners, or other entities that still point to deleted projects, trackers, items, users, roles, or groups.
|
|
DELETED_ROLE_REFERENCE
|
References to project roles that no longer exist in the project.
|
|
INVALID_COMPUTED_FORMULA
|
Computed fields with broken formulas or references that cannot be evaluated. This includes guards, conditions, and workflow actions that reference deleted or inaccessible trackers, items, or foreign filters. Without this report, such transitions can fail silently or perform no action.
For details about computed fields, see Computed Fields.
|
|
INVALID_QUERY
|
cbQL queries with syntax errors or invalid references that cannot be executed. This includes saved queries, tracker view criteria, traceability queries, and baseline or history-baseline references that cannot be parsed or resolved. These issues often result in empty dashboards, widgets, and reports without visible errors.
For details about cbQL, see cbQL.
|
|
NON_MATCHING_REFERENCE_FILTER
|
Field values that do not satisfy the configured reference filter conditions.
For details about reference fields, see Reference Fields.
|
|
INVALID_GUARD_OR_CONDITION
|
Workflow guards or action conditions that reference invalid or deleted tracker views.
For details about guards and actions, see State Transitions.
|
|
BRANCH_REFERENCE
|
References to tracker branches, which are not supported in project exports. This includes references to branched artifacts, items, or tracker types that deployment does not support.
For the definition of branch, see Merging Trackers into Streams.
|
|
NOT_SUPPORTED_ARTIFACT_REFERENCE
|
References to artifact types that cannot be exported or are not supported.
|
|
NOT_SUPPORTED_WIKI_ARTIFACT
|
Wiki page references to artifacts that are not supported in a wiki context, such as invalid markup or ordinal references within wiki pages.
For details about wiki pages, see Wiki.
|
|
NOT_SUPPORTED_ITEM_TYPE
|
References to tracker items of types that are not allowed for export.
|
|
NOT_SUPPORTED_TRACKER_TYPE
|
References to trackers of types that are not supported for deployment configuration.
|
|
INVALID_REFERENCE_FILTER
|
Reference filter definitions that contain invalid tracker view artifacts.
For details about tracker views, see Tracker Views.
|
|
INVALID_TRACKER_IN_CRITERIA
|
Tracker view expressions that reference trackers that do not exist or are inaccessible.
For details about tracker views, see Tracker Views.
|
|
NO_EXPORT_PERMISSION_FOR_TRACKER
|
References to trackers for which the current user does not have the export permission or Item - View if Owner tracker permission. The report indicates which trackers are skipped during deployment for the user who runs the export.
|
|
DELETED_REFERENCE or INVALID_REFERENCE
Descriptor: INVALID_WORKFLOW_ACTION
|
Workflow state transition actions that contain references to trackers in foreign item filters that are either deleted or inaccessible.
For details about workflow actions, see Workflow Actions.
|
|
|
The Project Health Report removes duplicate entries automatically. If the same invalid reference appears in multiple locations in the project, the CSV report contains only one entry.
|
Best Practices for the Project Health Report
To detect configuration issues early and to maintain a stable project structure, run the Project Health Report in the following scenarios:
• Before every project configuration deployment.
• After significant deletions or configuration changes, such as changes to trackers, fields, workflows, or the project structure.
• During troubleshooting, when project members report unexpected behavior.
• During scheduled system maintenance windows.
• Before upgrading Codebeamer.
Scope and Limitations
The Project Health Report has the following scope:
• Single project—Validates only the selected project.
• Configuration-level—Validates project settings, trackers, fields, workflows, and views.
• Reference integrity—Identifies broken references and invalid dependencies.
• Export readiness—Verifies that the project can be exported successfully.
The Project Health Report does not validate the following areas:
• Direct references in computed formulas—The report does not validate inline references in expressions, such as hideIf or mandatoryIf, calculated field formulas, runtime formula execution, or field availability.
• Cross-project dependencies—The report validates only the specified project with a validation depth of one level. It verifies references from the current project to other dependent projects but does not validate the configuration of those dependent projects.
• Runtime errors—The report detects only configuration-level issues and does not validate runtime behavior.
• Data integrity—The report does not validate the content of tracker items.