Troubleshooting Guide for the Project Configuration Deployment
This guide describes common challenges and specific observations for Project Configuration Deployment scenarios.
Defining the Environment-Independent Entity and UUIDs
To match automatically deployed entities of independent environments, each entity must have an environment independent identifier that matches across environments. Codebeamer uses a Universally Unique Identifier (UUID) for entities to achieve this. The UUID is used to identify a Codebeamer entity that is generated at creation time. All entities must contain this unique identifier.
The equality of the UUID defines the connection between the original entity on the source server and the imported entity on the target server. The UUID cannot be NULL.
Creating and Updating Projects with a Configuration Deployment
The project configuration deployment is extended to handle UUIDs. As a result, Codebeamer users are not required to do manual mappings, as Codebeamer manages the processes automatically. The missing projects and their entities are also created.
Merging is not supported. However, Codebeamer overrides the existing project configurations and work items from the export. As a result, the tracker configuration customizations and work item updates are deleted on the target server. For example, you must also remove the following from the target environment:
• Configuration item values that were deleted from the source environment and have become obsolete.
• Deleted fields.
Certain entities are transferred in a non-disruptive manner:
• Groups and roles are extended and updated only with the entries from the source environment that do not exist on the target.
• Entries that exist in the target system but not on the source system are deleted.
• Group-role mappings are also retained to prevent the deployment function from jeopardizing the integrity of the target system.
Recursive Project Export
Project export is extended with UUIDs. Entities in the export file contain UUIDs that are handled in the configuration deployment processes. To handle the references between projects in the configuration deployment, all related projects must be identified.
Codebeamer analyzes tracker configurations in the selected project at export time, and finds other elements such as reference fields, actions, or conditions. Based on the references, Codebeamer can identify the connected projects. The analysis is implemented recursively to export all entities on which the source project depends. These projects with their entities are part of the exported package. Multiple project exports are supported. The export process is extended with UUIDs for entities.
Entities from the Trash tab of a project cannot be exported. If deployment entities have references to the trash, the conflicts must be resolved to allow a seamless deployment process. Users must permanently remove the entity from the trash, or remove the entity references from the configuration. Codebeamer does not allow users to export projects with such references.
The below example shows how a recursive project export works on multiple projects.
The setup contains six projects (projects from 1 to 6) and seven references (references from 1 to 7).
If project 1 is selected for export, all projects from 1 to 6 are also exported by default.
In this use-case, consider the export of project 1. To find dependencies of this project, Codebeamer identifies the upstream and downstream references. Based on these references, all related projects are identified and included in the exported package by default.
Resolving Reference Issues During a Deployment
If the deployment finds invalid references, you get the following warning:
To troubleshoot this scenario, do the following:
1. Download and unzip the export file.
2. Open the invalidReferences.csv file.
3. Locate the root cause in the Reason column of the CSV file.
4. Resolve all the issues listed in the Reason column before attempting a new deployment.
◦ For more information on resolving reference issues, refer to Project
Import and Export Restrictions.
Including Independent Projects as Part of the Deployment Payload
In the following scenario, the corporate project is also part of the deployment due to the inheritance and dependencies related to the derived project:
To include the independent project in the deployment payload, create a reference from derived project to independent project, so that Codebeamer is able to recognize it as a dependency, as in the following diagram:
By doing so, the deployment background job determines all the dependencies of the derived project and includes the independent project in the deployment while resolving item references.
For more information about the projects available for deployment, refer to Availability of Projects
in a Selective Deployment.