Project Configuration Deployment Across codebeamer Instances

This page describes codebeamer's Project Configuration Deployment function.

Since codebeamer 10.1, Project Configuration Deployment allows transferring and updating complex project hierarchies between codebeamer instances. See the supported entities at Project Configuration Deployment - Technical Details.

In the future, this functionality is intended to replace both the Project Configuration Merge and the Export/Import features of the preceding codebeamer versions. Switching to the new functionality is highly recommended.

Known Limitations

Configuration Limitations

• Changing the imported entities are possible on the target system, but highly not recommended.
• Deletion on the target system is not supported by all entities. For details, see Project Configuration Deployment - Technical Details.
• The source and the target codebeamer versions must be the same.
• Since EMMA 21.09: Project Configuration Deployment does not support applying configurations that were exported in a pre-EMMA environment.
• Since EMMA 21.09-SP5: When items are transferred with Closed status, the tracker configuration needs Item - Close permission. In case the permission is missing, the deployment process throws an error: User {user} has no permission to close {item}.
• Since Felicity 22.04: Project Configuration Deployment does not support new Tracker Item Templates.

Export Limitations

• The export is to contain only those items which the initiator has access to. Therefore, the user performing the configuration deployment needs to have both system admin and project admin rights on all related, referenced projects.

• Reference finder only works through reference filters, other dependencies will be excluded.
• Exporting a project with a working set will ignore the working set configurations.
• Updating an existing project with a working set configuration is not supported via deployment.
• Closed projects are not supported.
• Users (and settings referring to specific users) are not exported/deployed.
• Wiki pages
• Document type trackers (before EMMA 21.09-SP5)
• Document type tracker items (since EMMA 21.09-SP5)
• Dashboard (since DOROTHY 21.04)

Limitations of Applying Configurations

• The following concepts are exported, but not applied on the target system:
  • Escalations
  • Notifications
  • Associations
  • Attachments
  • Configuration icons
  • Project calendars
    
• Computed formula updates are only partially supported:
  • ID references in computed formulas are not resolved and updated.
    
• cbQL updates are partially supported:
  • custom field references are not replaced during deployment.
    
• Artifacts are only partially supported, only the artifacts under the .codebeamer folder are transferred over.
  
• Deletion of tracker configurations on the target environment are not fully supported. For details, see Project Configuration Deployment - Technical Details.
  
• Deletion of tracker configurations on the source environment is not supported.
  
  
• Due to certain technical limitations, tracker inheritance is not fully supported and may result in slightly changing tracker configurations when applied.
  
  
• If there are trackers in the Trash which are having a currently deployed tracker as a template, the template (inheritance) connection between those will be removed.
  
  
• Not supported configurations:
  • Broken project category references
  • MxGraphs
  • Broken user references
    
    
• Project Category Hierarchies will not be applied to the target system. All categories will be merged to the root level.
  
  
• When the deployment of the document trackers is disabled, these trackers are missing from the tracker outline of the project after an import. The child trackers of this project are flattened in the tracker hierarchy.

User Guide

The project configuration deployment consists of 2 consecutive steps:

1. Exporting the project (and its dependencies) for the deployment from the source codebeamer instance
   
   
2. Applying the deployment on the target codebeamer instance

Exporting Projects from the Source Instance (up to DOROTHY 21.04)

1. Open the Admin page of the project to export
   
   
2. Click on the Export for Deployment link
   
   
3. The overlay dialog displays all the projects the exported package will include
   
   
4. Even items within a tracker can be selected for deployment to another codebeamer instance
   
   
5. The export can be encrypted with a password to prevent unauthorized access and importation of project data.
   
   
6. Click on [Export] and save the deployment archive on the local machine

Exporting Projects from the Source Instance (since EMMA 21.09)

1. Open the Admin page of the project to export

2. Click on the Export for Deployment link

3. A background job will start to discover the dependencies of the project. WebSocket and email notifications will inform the user about the statuses of the background job.

4. Once the job finished, navigate to the Exporting Project and its dependencies window:

• The dependent projects are listed in an accordion choice list. To unfold the list of trackers, click on the name of the project.
  
  
• Besides the items selected by default, further items of any trackers can be selected for the deployment. Items selected by default are the ones that had been exported in the preceding project deployment.
  
  
• Include items are selected by default for the following tracker types:
  • Configuration Item
  • Release
  • Component
  • Platform
  • Contact
  • Testset
  • Testconf
  • Team
  • Area

UI changes in codebeamer 22.04 (FELICITY):

• The number of the items is displayed in a table column.

Exclude Projects and Trackers from the Deployment Export

Selective Deployment is disabled by default, and can be enabled in the Application Configuration by a System Administrator.

"deployment" : {
    "enableSelectiveDeployment" : true,
}

When Selective Deployment is enabled, projects and trackers can be deselected for the deployment.

Saving Selective Deployment Settings

• To save the Selective Deployment Export settings into a JSON file, click on the [Save settings to a file] button:
  

Loading Selective Deployment Settings

• To load Selective Deployment Settings, click on the [Load settings from a file]:
  

• The loaded JSON file is getting validated, and several warning messages can appear based on the problems found.
  

Enable Document Type Tracker Export

The "enableDocumentTrackers" configuration is available since codebeamer release 21.09-SP5 (EMMA).

To enable the deployment of the document type trackers and their configurations, the following configuration needs to be added to the "deployment" section in the System Admin ► Application Configuration

"deployment" : {
    "enableDocumentTrackers" : true,
    "enabled" : true
}

• If the parameters are set to true, the deployment export page lists the document type trackers, and their configuration is included in the export by default.
• The document type tracker items are not included in the export, but can be selected individually on the export page.

Applying Deployment on a Target Instance

1. Go to Projects ► Apply project deployment
   
2. Upload the deployment archive downloaded from the source environment, and provide the password if needed (only required for encrypted archives).
   Archives created by functions other than the Export for Deployment is incompatible with Apply Project Deployment function.
   
3. Clicking on [Apply] starts the deployment in the background.
   
4. A message is displayed when the deployment finishes.