Importing and exporting projects
This topic describes how to use the Import/Export Manager to move projects between StarTeam servers.
Import/Export Manager business rules
The following rules are used when you run the Import/Export Manager:
Artifact Number Mapping | All the artifact numbers (change request number, requirement number, etc) are remapped to a new number in the target. If the change request has been shared across multiple views or sand boxes, the change request number will remain intact. The older change request number will be stored in a custom field for cross referencing purposes. | ||||||
Broken shares and links |
|
||||||
Cross project shares and Links | Cross project shares are shares whose parents reside outside the selected projects boundaries. These shares and links are broken by Import/Export Manager and reset to be root items. The branching behavior of these items is reset to model a root item. If the source item is pinned, the pinned behavior is carried over to the target. | ||||||
Custom Components | Custom component names are matched by their internal name during import. If there is a match found on the target server for a given component name, the source and target components are considered to be the same. If a match is not found, a new custom component will be created on the target server and all its associated data, properties, and enumerations will be copied over. It is the responsibility of the user to review their source and target components and see if there are matching custom components which are not related but happen to have the same internal name. In this case, the user will have to rename either the source/target component before import. | ||||||
Custom Properties | For components on the source and target server that match, the import operation iterates through all the custom properties
available and checks to see if a custom property with the same internal name for the component exists on the target server.
If it is not found, this property will be created on the target server.
Microsoft SQL Server has limitations with the row length and importing a large number of custom properties could potentially cross the row length limit. One way to avoid this issue is to exclude disabled properties from being carried over. The Exclude disabled properties check box is provided during export. This will ensure that all the catalog field/enumeration entries and the values for the disabled properties on the source server are not imported. Before custom properties are added to the target server, Import/Export Manager will do a row length check to determine if the target database table allows new columns to be added. Import/Export Manager will not continue if this check fails. Please also consider:
|
||||||
Deleting projects from source server | Import/Export Manager does not delete the Projects selected for export from the source server. It is up to the user to decide based on their requirements. | ||||||
Filters, Queries, and Audits | Filters, queries, and audits will not be imported by default. This can be changed in the user interface. | ||||||
Hives |
In addition to the database metadata, the Import/Export Manager also copies over vault contents to the target server. If the target server has multiple hives, the contents are added to all the hives in a round-robin fashion, similar to the way StarTeam Server processes content. The Import/Export Manager does an up front estimation of the total size of the vault content being exported from the source and checks to see if the target hive has the capacity to handle importing the contents. If there is not sufficient storage space, the Import/Export Manager will throw an error message and abort the operation before importing any data. Estimation of space on the target hives depends on various parameters like storage threshold limit of the hive, disk partition capacity, and also the Allow new Archives option. It is recommended that you ensure that there is ample disk space on the target machine and that the hives are configured appropriately before starting import. File contents, attachments, and contents from content properties are copied over to the target as is, without any processing. Change package attachments, however, need to be processed before being imported to the target server. Change package attachments have ids embedded in the content. They need to be re-mapped to the corresponding id in the target. The imported contents will therefore end up having a different md5 value compared to the one in source. This is essential so that the imported change packages can be opened and used. |
||||||
Licenses | Import/Export Manager does not copy over the source server's licensing information. It is important for the user to ensure that the target server is licensed appropriately. For example, if the source server has enterprise advantage license, and the user is importing requirements data from this server to the target server, it is required that the target server has an enterprise advantage license to view the imported requirements. | ||||||
Source and Target Servers | Source and Target StarTeam Servers must be running the same build number. | ||||||
Tip Items | If a tip item is moved across project boundaries, the historical revisions of the item will be available in the target to support rolled back configurations. The tip item will not be available in the target since it does not belong to the imported project. |
Import/Export Manager
The Import/Export Manager provides performance and scalability improvements by allowing you to selectively move projects from one StarTeam Server to another StarTeam Server. There are many reasons to have multiple servers. In this case, you may want to archive old projects from your active server or simply separate your different business units. Having the ability to move projects around will provide limitless opportunities for you to keep your active servers lean and full of only the most important projects.
For important information on how your data will be migrated, see Import/Export Manager business rules .
Exporting a project
Use the Export Window to export one or more projects from a Local server configuration into a file on your computer. To access the window, click Tools > Import Export Manager > Export.
Note: You must stop the server configuration before you can export a project.
Select projects to export | Select one or more projects to export. |
Select all projects | Click to select all of the projects in the Select projects to export list. |
Ignore filters and queries | Click to exclude filters and queries from the export file. |
Choose a location for the export file | Click Browse to select a location for the export file. |
Export | Click to begin the export process. |
Export one or more projects from a local server configuration into a file on your computer. After that, you can import the project into another StarTeam Server.
Note: If you are moving projects within your Local server configuration, you do not need to export them first. You can go directly to the import process.
To export a project:
- Open the Server Administration tool.
- Select a server configuration.
- Stop the server.
- Click . The Export window opens.
- Select one or more projects to export in the Select projects to export list.
- Click the Select all projects checkbox to select all of the projects in the Select projects to export list.
- Click Ignore filters and queries to exclude filters and queries from the export file.
-
Under the
Choose a location for the export file
field, click
Browse to select a location for the export file.
The export file will be named the same name as the configuration and contain a .stbk extension.
- Click Export to begin the export process. The Import/Export Manager begins the export process and displays progress in a window. The message, The export operation completed successfully, will be displayed when the export is done.
Importing a file
This section describes how to import a previously exported file. For an understanding of how your data will be imported, see Import/Export Manager business rules .
Note: Make sure you read the Business Rules topic to understand how your data will be imported.
Use the following steps to import a previously exported file into a local server configuration.
- Open the Server Administration tool.
- Select a server configuration.
- Stop the server.
-
Click
Note: You can also import directly from a local server configuration. Click . Select the server configuration and ignore the next step.
.
- Next to the Choose file on disk to import from field, click Browse to select the backup file to use.
- Check the Merge Users and Groups checkbox if you want to merge users and groups.
- Check the Rename projects upon conflict checkbox if you want to have projects renamed upon conflict. If there is a conflict, you will be given a chance to rename the imported projects.
- Check the Ignore filters and queries checkbox if you want to ignore filters or queries during the import.
- Check the Ignore Audits checkbox to ignore audits during the import.
- Check the Ignore disabled properties in source server checkbox if you want to ignore properties that have been disabled on the source server.
- Check the Intervene upon merge conflicts checkbox if you want to show all conflicts in a window during import. From there, you can choose to either use the source or target values.
- Click Import. If you selected Intervene upon merge conflicts and there are conflicts, the Handle conflicts during import dialog box displays. Select how you want conflicts to be handled. A message, The Import operation completed successfully, displays when the import is complete.
Import window
Use the Import window to import a backup file into a Local server configuration. To access the window, click
.Note: You must stop the server configuration before you can import a project.
Choose file on disk to import from | Click Browse to select the backup file to use. | ||||||||||||
Handle Merge conflicts | Contains different options allowing you to control how conflicts are handled.
|
Handle conflicts during import dialog box
The Handle conflicts during import dialog box displays when:
- There are assets in the source and target that appear to be the same.
- You checked the Intervene upon merge conflicts checkbox on the Import window.
Review the conflicts in the list on the dialog box and select how you want the conflicts to be handled.
For users and groups, you will see:
Use Source | Selecting this option will override the values in the server configuration with the values in the backup file. |
Use Target | Selecting this option will ignore the conflicting values in the backup file and use the values from the server configuration. |
Do the same for all remaining conflicts | Selecting this saves whichever option you selected, Use Source or Use Target, and applies it to all merge conflicts. |
For project name conflicts, you will see:
Default action is to rename project using suffix (ConfigName.stbk). | Select to let the application rename the project for you. |
Rename project using alternate suffix instead. | Type in the name of the project in the field. |
Best practices and limitations
Follow these best practices:
- Always backup the target database before running an import. The import process significantly changes the target database and if the import fails, the target database may be unusable.
- It is strongly recommended to do multiple test runs against a copy of the database and the vault before it is deployed in production.
- Import/Export Manager copies significant amount of data to the target database. It is important to ensure that target server machine and database machine have available free space to support this import.
The following limitations apply when using the Import/Export Manager:
- This version of Import/Export Manager supports Microsoft SQL Server, Oracle, and PostgreSQL databases. You cannot copy data between Oracle and Microsoft SQL Server or PostgreSQL but you can copy between PostgreSQL and Microsoft SQL Server.
- This version of Import/Export Manager does not offer a command-line option.
- This version of Import/Export Manager does not offer the option of re-starting. If the import operation fails due to unexpected reasons, the target database may be left in a bad state. It is very important to take a backup of the target database and the vault before importing. In case of failure, the Import/Export Manager will write the error messages and the stack-trace detailing the reason for the failure. After resolving the issue, the user should not use the copy of the database involved in the failed operation but should use a new target database backup from pre-import time.