Tags: Project Configuration Deployment

Project Configuration Deployment - Technical Details

This page summarizes the technical details of the project configuration deployment.

Defining Entities

The term Entity is used for codebeamer artifacts such as:

User groups
Project roles
Project categories
Global fields
Projects
Trackers
Wiki page and Dashboards
Documents
Comments / Attachments
cbQL queries
Configuration type tracker items

Exceptions

The following types are not part of the configuration deployment, and are not considered as entities in the scope of this documentation:

Associations
Baselines
Branches
Escalation rules
User accounts
Review hub reviews
Notification settings
Tracker template inheritance references
Work item type tracker items
Calendars
Tags

Supported References

Projects
Trackers
Work items
Roles
User groups
Global types (only in cbQL queries and in tracker field settings)

The following references are out of scope for Solution 1:

Repositories
Users
Branches
Work item revisions

The detailed reference of entities can be found at the end of this document.

Key Challenges

The key challenges the enhanced configuration deployment function needs to solve are

Environment independent entity identification
Recursive project export
Project create and update with configuration deployment

The following sections describe possible solutions to solve these challenges.

Environment Independent Entity Identification

To be able to match automatically deployed entities of independent environments, each entity needs to have an environment independent identifier that matches across environments.

codebeamer uses Universally Unique Identifier (UUID) for entities to achieve this.

Universally Unique Identifier - UUID

The UUID is used to identify a codebeamer entity. It is generated at creation time, and all entities must contain this unique identifier, so it cannot be NULL.

Origin UUID

The origin UUID is used in imported entities only. It is set during the configuration deployment process, and contains the UUID of the original entity. With the original UUID, the connection between original and imported entities can be defined. If an entity is not connected to another entity, this value can be NULL.

UUID Before codebeamer 10.1.0 Version

Many codebeamer projects do not have UUIDs. To support such projects, an upgrade script is available to generate UUIDs for all existing codebeamer entities. Once the script is executed, the affected projects can be handled the same way as new projects in codebeamer release 10.1.0.

In order to make the deployment function work between source and target projects created before the enhanced deployment function, the origin UUID of the target entity needs to be set manually.

Recursive Project Export

Project export is extended with UUIDs. Entities in the export contain UUIDs which are handled as origin UUIDs in configuration deployment processes. To handle the references between projects in configuration deployment, all related projects need to be identified.

codebeamer analyzes tracker configurations in the selected project at export time, and finds reference fields, actions, conditions and so on. Based on the references, codebeamer can identify the connected projects. The analysis is to be implemented recursively so that all entities the source project depends on can be exported. These projects are part of the exported package with their entities (multiple project export are supported). The export process is extended with UUIDs for entities.

Entities from the Trash cannot be exported. In case such references are found, the users need to resolve the conflicts. Either the entities should be removed permanently from the Trash, or the references are to be removed from the configuration. codebeamer does not allow users export projects with such references.

The below example shows how recursive project export works on multiple projects.

CB:/displayDocument/1588764881233.png?doc_id=10617677&version=1&link_id=10617678&raw=true&history=false&notification=false

If Project 1 is selected for export, all projects (1-6) are exported by default. The setup contains six projects (Projects 1-6) and seven references (References 1-7).

In this use case, Project 1 is being exported. To find dependencies of this project, codebeamer identifies the upstream and downstream references based on which all related projects are identified and included in the exported package by default.

Creating and Updating Projects with Configuration Deployment

Project configuration deployment is extended to handle UUIDs and origin UUIDs. As a result, codebeamer users do not need to do manual mappings in the future since the processes are managed by codebeamer automatically (missing projects and their entities are created as well).

Merging is not supported, however, codebeamer overrides the existing project configurations and work items from the export, so the tracker configuration customizations and work item updates are deleted on the target server. As an example, configuration item values that have been deleted from the source environment are to be made obsolete, and fields that have been deleted should also be removed from the target environment.

However, certain entities are to be transferred over in a non-disruptive manner:

Groups and Roles are only to be extended and updated with 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 not to be deleted.
Group-Role mappings are also to be kept so that the deployment function cannot jeopardize the integrity of the target system.

Detailed Entity Descriptions

Global Type

All Global types are moved between the source and the target systems. Renaming Global type is supported.

Link Type	UUID
Limitations	A Global Type with an existing name on the target system cannot be created.
Deletion	Not supported

Role

All Roles are moved between the source and target systems.
These are template roles used by project roles.
New roles with the new names are created.
Renaming is not supported. Existing roles are found by name and reused.

Link Type	Name
Limitations	Not known
Deletion	The roles cannot be deleted on codebeamer UI. Roles are not deleted on the target system.

User Group

All user groups are moved between the source and target systems.
New user groups are created.
Existing user groups are found by name.
Rename is not supported.

Link Type	Name
Limitations	Not known
Deletion	Not supported

Report

All public reports are moved between the source and the target systems.

Link Type	UUID
Limitations	The name of an entity can be used in cbQL as reference. These names are not resolved during the import.Entities with numeric names (for example 123 as a project name) are either resolved incorrectly or they break the import.
Deletion	Not supported

Project

All exported projects are moved between the source and target systems.

Link Type	UUID
Limitations	Projects with existing names on the target system cannot be created. Project images are not moved from the source to the target systems.
Deletion	Not supported

Project Role

All project roles are moved between the source and the target systems.
New roles are created.
Existing roles are updated.
Neither on the codebeamer UI, nor in the configuration deployment is the Project Admin role update supported.

Link Type	UUID
Limitations	Project role swap is not supported. Project role with an existing name on the target system cannot be created.
Deletion	Not supported

Project Category

All project categories are moved between the source and the target systems.
Renaming project categories is not supported.
New categories are created on the target system.

Link Type	Name
Limitations	Not known
Deletion	Not supported

Project Category Hierarchy

All project categories are moved between the source and the target system.
Source and target project categories are mixed.

Link Type	Name
Limitations	Project Category Hierarchies are not applied to the target system. All categories are merged to the root level.
Deletion	Not supported

Project Tracker Tree

Tracker tree is moved between the source and the target systems.
Source tracker tree overrides the target tracker tree.

Link Type	-
Limitations	-
Deletion	Supported

Project Wiki and Dashboard

All project wiki pages and dashboards are moved between the source and the target system.
Source and target wiki pages and dashboards are mixed.

Since codebeamer release 21.04 (DOROTHY), Dashboards are not exported.
Since codebeamer release 21.09-LTS (EMMA), Wiki pages and Documents are not exported.

Link Type	UUID
Limitations	Wiki pages and dashboards with an existing name on the target system cannot be created. User references are not resolved in wiki pages.
Deletion	Not supported

Tracker

All trackers are moved between the source and the target system.
All tracker attributes are moved between the source and the target system.

Link Type	UUID
Limitations	Trackers with existing names within a project on the target system cannot be created. References in the configuration use the head revision of selected entities (work item, project, tracker, etc.) Settings are overwritten and, if possible, the deleted fields on the source system are deleted on the target system as well. Deleting a work item field with values from the target system causes unresolvable problems. Instead of deleting such a field, making it read-only and hidden is recommended. Email inbox settings are not supported.
Deletion	Not supported

Details of Tracker Configuration Update

The project configuration update is a complex process: codebeamer creates and updates several entities and their attributes.
Existing entities are overwritten (customizations are deleted on the target server) while non-existent ones are created.
Customizations may cause errors, therefore, configuration deployment to target servers with modified tracker configurations are not supported.

Tracker Entities

For tracker entities, the following settings are updated:

General attributes
Permissions
Workflows (transitions and actions)
Fields
Service desk attributes

Escalations and Notifications are not updated. These can be customized on the target server.

Details of Tracker Reference Update

codebeamer updates reference settings and values as well in the tracker configuration.

The following references are replaced in the configuration:

Tracker fields
- Default value
- Allowed value
- Reference filters
- Combination values (depends on)
- Calculated fields and conditions
View type configurations (i.e. guards, conditions, etc.)
Shared tracker view configurations
Workflows
- Transitions
  - Guard
  - Actions
    - Condition
    - Foreign item filter
    - Fields updates
    - Parameters

Tracker View

All tracker views are moved between the source and the target systems (For instance, guards, action, conditions, etc.).

Link Type	UUID
Limitations	Tracker views with existing names cannot be created on the target systems.
Deletion	Not supported

Tracker Dashboard