Importing and exporting projects

This topic describes how to use the Import/Export Manager to move projects between StarTeam servers.

In this topic:

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	The export process evaluates all the shares and links that cross the selected project boundaries. Shares and links that cross project boundaries, but are within the list of exported projects, are not broken by Import/Export Manager. For those shares whose parent or root is in a different project which is not being exported, Import/Export Manager will make this item its own root. It will reset the branching behavior to model a root item. Links with either the source endpoint or the target endpoint outside the project scope will be ignored and will not be exported.
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: Property with the same internal name but different enumerations If two enumerated (single/multi-select) custom fields have the same internal name and the same type, the target server configuration must have the enumerations found on the source as well as those found on the target. For example, if the source field has 100 red, 200 blue, and 300 white and the target field has 100 blue and 200 orange, Import/Export Manager will add red and white to the list of enumerations for the target field. Import/Export Manager will see that the 200 blue is equivalent to the 100 blue and ignore orange, but it needs to find red and white, regardless of their code numbers. After the import, this field will have the following enumerations on target server configuration for this example field: 100 blue, 200 orange, <some number> red, <some number> white. Import/Export Manager preserves the values (visible to users) and does not worry about the code numbers. However, you may want to set up the extra enumerations needed on the target server manually before importing to control those codes. Disabled enumerations are still copied for enabled custom fields because some items may have those values. The enumerations will be disabled on the target unless the target field already has an equivalent enabled enumeration. The default values for an enumerated property are not merged. Custom property being added to the target already exists with the same data type but different length The target custom property's length will be increased to prevent data truncation issues for the imported data. Custom property being added to the target already exists with a different data type Import/Export Manager will create a new custom property with a system generated name.
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.

Back to top

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.

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.

To export a project:

1. Open the Server Administration tool.
2. Select a server configuration.
3. Stop the server.
4. Click Tools > Import Export Manager > Export. The Export window opens.
5. Select one or more projects to export in the Select projects to export list.
6. Click the Select all projects checkbox to select all of the projects in the Select projects to export list.
7. Click Ignore filters and queries to exclude filters and queries from the export file.
8. 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.

9. 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.

Back to top

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 .

Use the following steps to import a previously exported file into a local server configuration.

1. Open the Server Administration tool.
2. Select a server configuration.
3. Stop the server.
4. Click Tools > Import Export Manager > Import from backup file.

   Note: You can also import directly from a local server configuration. Click Tools > Import Export Manager > Import from server configuration. Select the server configuration and ignore the next step.

5. Next to the Choose file on disk to import from field, click Browse to select the backup file to use.
6. Check the Merge Users and Groups checkbox if you want to merge users and groups.
7. 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.
8. Check the Ignore filters and queries checkbox if you want to ignore filters or queries during the import.
9. Check the Ignore Audits checkbox to ignore audits during the import.
10. Check the Ignore disabled properties in source server checkbox if you want to ignore properties that have been disabled on the source server.
11. 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.
12. 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.

Back to top

Import window

Use the Import window to import a backup file into a Local server configuration. To access the window, click Tools > Import Export Manager > Import from backup file.

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. Merge Users and Groups Select to merge users and groups. Rename projects upon conflict Select to have projects renamed upon conflict. If there is a conflict, you will be given a chance to rename the imported projects. Ignore filters and queries Select to ignore filters or queries during the import. Ignore Audits Select to ignore audits during the import. Ignore disabled properties in source server Select to ignore properties that have been disabled in the source server. Intervene upon merge conflicts Select this option to show all conflicts in a window during import. From there, you can choose to either use the source or target values.

Back to top

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.

Back to top

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.

Back to top