Prepare and Deploy Project Configuration

Preparations: Before initiating a project configuration deployment procedure, you need to export a project configuration file from the source project. For more information, see section Export Project Configuration File as Project Template.

To prepare the configuration of your new project and deploy the project configuration, follow the steps below:

1. In the target project, go to the Admin menu and select Settings:

2. In the Administration window, click Import and select Deploy Project Configuration:

The Upload Source Project File window opens.

3. In the Project File field, attach the source project file which contains the configuration that you want to map to your new project:

The source project file is a project configuration file which was exported from the source project as a project template.

A mapping file is created during the project configuration deployment procedure and it contains the mapping between a specific source and target project. If you performed a project configuration deployment procedure before for the same mapping as in the current procedure (between the same source and target projects), then you can use the mapping file created during that procedure to make the deployment process faster and more simple (see Download Project Mapping File).

If you have a mapping file created during a previous deployment procedure, upload that file in the Mapping File field.

When you are finished uploading your files, click Next to go to the next step.

The Project Artifact Mapping window opens.

4. Map the imported project artifacts to their counterparts in the target project. A default mapping is provided based on artifact names and types, but you can make any modifications in the mapping as applicable:

The following types of artifacts need to be mapped from the source to the target project:

• Project Properties: in this section, you can select the project properties that you want to overwrite in the target project (based on the source project file). All the properties can be selected in this section that you can configure on the project configuration page (that is, under Admin > Settings > General tab).
• Roles: in this section, you can define the mapping in project roles between the source and target projects. Permissions to trackers are based on project roles. If you map a role in the source project to a role in the target project, the target role will get all permissions set for the matching role in the source system. By default, the system identifies a matching role in the target project for each source project role. If there is no role in the target project that the system can identify as a matching role to a source project role, the value "Create in Target Project" will be selected for that role by default. You can still use the drop-down menu to select any role in the target system as a target role for a source project role:

• User Groups: in this section, you can define the mapping in user groups between the source and target projects. It is important to map user groups to the target project, as user groups can be used as reference field filters in trackers and reports.
• Project Categories: in this section, you can define the mapping in project categories between the source and target projects. This is relevant especially when you are mapping project configurations between projects which are in two different codeBeamer instances. You also have the option to create a new project category in the target system if it does not exist yet.
• Trackers: in this section, you can define the mapping in trackers between the source and target projects. By default, the system identifies a matching tracker in the target project for each tracker in the source project based on the names and types of trackers. You can change the default mapping for any tracker by selecting a new target tracker from the drop-down menu.

In case the system cannot identify a target tracker matching a source tracker by default, the system will select the "Create in Target Project" option for the tracker. You can still select any tracker from the drop-down list as a target tracker for this source tracker. You can also select the "Ignore" value for these trackers, which means that the tracker will not be created in the target project:

You cannot map more than one source tracker to the same target tracker. If more than one source tracker is selected to be mapped to a target tracker, the invalid rows will be marked with a light red background color.

In case there is no tracker in the source project matching a target tracker, you can delete that tracker in the target project during the mapping process. By default, these trackers are ignored by the system, that is, they are not deleted from the target project, but they are also not updated based on any source tracker:

If you want the system to only display those artifacts in the Project Artifact Mapping window which have no default mapping identified by the system, click the Show only artifacts with no default mapping checkbox:

When you are finished mapping artifacts in one section in the Project Artifact Mapping window, you can mark that section completed:

When you are finished mapping artifacts, click Next to go to the next step.

The Branch Mapping window opens.

5. Map tracker branches to their counterparts in the target project:

This step is based on the mapping of trackers in Step 4. If you mapped a source tracker to a specific target tracker, then you can only map branches of that source tracker to branches of the selected target tracker (if any).

You also have the option to create the branch in the target project or to ignore this branch. If you select the "Ignore" value, the branch will not be created or mapped to any branch in the target project:

When you are finished mapping tracker branches, click Next to go to the next step.

The Tracker Field Mapping window opens.

6. Map tracker fields from the source to the target project:

A default mapping is provided based on field names and types, however, you can change the mapping for any custom or choice fields in your trackers.

It is not possible to change the mapping for fields which are included in a specific tracker type by default. These fields are marked with a light red background in the list:

If you want the system to display those fields only which are not default (or "built-in") fields, click the Hide built-in fields checkbox:

You can create tracker fields in the target project which are not created yet, and delete or ignore fields which are only created in the source or target project:

When you are finished mapping tracker fields, click Next to go to the next step.

The Mapping Cross-Project References window opens.

7. Map cross-project references from the source to the target project:

This step is relevant especially when the source and target projects are in two different codeBeamer instances. In this case, it is possible that the source project contains references to specific (external) projects, trackers, fields, or users in the source system which do not exist in the target system. These references can be, for example, the default or allowed value of a field, the owner of a tracker, and so on. As these external references are not part of the exported project configuration and do not exist in the target system, you need to specify the mapping for these references in the target system. That is, you need to select the project, tracker, field or user which these references correspond to in the target system.

The following types of cross-project references need to be mapped to the target project:

• Projects: this section contains the cross references to other projects which are used in the source project configuration. In the Target field, select the corresponding reference project in the target system. If you expand the Used in field, you can see which field (in which tracker) has a reference to this external project in the target system.

• Trackers: this section contains the cross-project tracker references which are used in the source project configuration. In the Target field, select the corresponding reference tracker in the target system, that is, the tracker to which the field indicated in the Used in field should refer.

• Users: this section contains the cross-project user references which are used in the source project configuration. For example, the owner of a tracker or a user in the member field configuration of a tracker. In the Target field, select the corresponding user in the target system, that is, the user to which the field(s) indicated in the Used in field should refer.

• Items: this section contains the cross-project item references which are used in the source project configuration. In the Target field, select the corresponding item in the target system, that is, the item to which the field indicated in the Used in field should refer.

When you are finished mapping cross-project references, click Next to go to the next step.

The Review Configuration window opens.

8. Review the project configuration that you specified in the steps described in this section:

This section provides a list of all the artifacts that you selected to be updated, created, deleted, or ignored during the deployment procedure. Ensure that all the specified mappings are correct in the configuration to be deployed.

When you are finished reviewing the configuration, click Next to initiate the deployment of the project configuration.

The deployment has now been initiated as a background process. You will receive a notification when the deployment is completed.