Folder Export/Import Tool - Best Practices

[Tonya]

What is the Folder Export Import Tool?

Vault Folder Export/Import allows you to copy the contents of a Vault folder to a different server or a different repository on the same server.

Folder Export will output the contents and history of a selected Vault folder to a local file on the file system. That file is then used to import the folder contents to a different Vault repository or server.

How to find the Folder Export Import Tool:

The Folder Export/Import user interface consists of a standalone application that is installed with the GUI Client. The same interface is used for both the exporting and importing data. It will exist in the Vault Client installation folder (usually c:\Program Files\Vault Client) as VaultFolderExportImport.exe. A shortcut will also exist at Start Menu->All Programs->SourceGear Vault-> Folder Export Import.

How to Export:

In order to export a folder to a file, take the following steps in the Folder Export Import user interface:

· Connect to a Vault server and repository that you want to export. Do this via the File menu, Connect to Server command. This is the usual process for logging into Vault, as you would do in the GUI client. The Choose Repository dialog will be automatically displayed after a successful login to the server. Make sure to log in using a user with admin privileges, such as the built-in Vault "Admin" account.
· You can change the repository at any time by invoking File->Choose Repository or Ctrl-P.
· After a successful login, the folder tree for the chosen repository is displayed in the main window. Choose the folder you want to export, and invoke the Export command (either view the toolbar button, the Action->Export menu item, the right mouse click context menu or Ctrl-E)
· This will bring up a dialog that allows you to specify a file you want the data to be exported to.
· The “Export Deleted Items” checkbox allows you to choose whether to export folders and files that have been deleted in the folder. If you do not export deleted items, they cannot be undeleted and retrieved when they are later imported. *** See below for suggested best practices ***
· The “Comment” text area allows you to store a description of the export in the data file, which will then be displayed later when the file is imported. This comment will not be put anywhere in the Vault database.
· Press “Begin Export” to start exporting data to the data file. A progress bar will give a general indication of how much data has been exported.

The repository does not have to be locked during the export – other source control activities can be happening simultaneously with the export.

However, note that no transactions applied to the folder after the export begins will be included in the exported data. For instance, if you check in a new version of a file within the export folder after the export begins (but before it finishes), that new folder version will not be reflected in the data file, and therefore will not be part of an import taken from that data file.

How to import:

In order to import a folder to a new server or repository, take the following steps in the Folder Export Import user interface:

· Copy the export file created during export to a file system accessible from the machine where you will be doing the Vault Folder import.
· Invoke the Vault Folder Export Import and log in to the server using an account that has FULL administrative rights to the repository to which you want to import the data, and choose that repository.
· Select the parent folder where you want the imported folder to be placed.
· Invoke the Import command (either view the toolbar button, the Action->Import menu item, the right mouse click context menu or Ctrl-I)
· The import dialog will be displayed, and has the following fields:
· File Name. The path to the export file to be imported. You can select this file from the local file system using the button to the right of the text field.
· Staging Folder: This is a temporary folder in Vault that is used to import all the data to before moving to its final location within Vault. A staging folder with a non-user-friendly name is used so that users won’t accidentally start apply source control transactions to the real folder before it is finished importing.
· Import to Subfolder. This determines whether or not the top level folder being imported should be created in Vault. To see the effects of this value, see how the “Import To Folder” field changes when this is toggled.
· Exported Folder. This is the Vault folder path that was previously exported, and is to be imported.
· Import To Folder: This is the folder to place the imported folders and files in the Vault server and repository you are currently connected to. The “Import to Subfolder” checkbox determines whether the top level folder is to be created at this location or not.
· Exported. This is the date/time the data was exported
· Comment. This is the comment that was entered during the export process that would contain a description or other relevant information about the export.
· Press the “Begin Import” button to begin the import. A progress bar will give a general indication of how much data has been imported.

As with export, an import can happen while other source control operations are taking place. However, import will have a greater performance impact on the Vault Server.

Best Practices:

Do not obliterate
Due to the behavior to remove historical information, Obliterate can cause issues with the Folder Export/Import feature. Avoid using the Obliterate operation from the Vault Admin site. To find out if any obliterates exist, you can run a history query on $/ (or the folder in which you initiated the export from), and in the Actions tab uncheck all actions except for obliterate. Are there any obliterates listed?

Export from root ($/)
When you export from root ($/), this will ensure that all the files needed when you invoke the import are available. Exporting from a sub-folder may prove troublesome if you have moved into, branched from share, shared or performed other actions on files and folders that exist in location within as well as outside of an exported sub-folder. By exporting from root ($/), you will ensure that all the necessary files are available upon import.

Include deleted items when Exporting
When initialing the Folder Export Tool, check the box to include deleted items as there may be dependencies of shares, branches, snapshots, etc. from delete items which could cause a failure upon import.

Use the most recent version
Make sure that you have the most recent Vault version installed (minimum recommendation is version 10.2.0).

To speed up the process
Use the Folder Export\Import tool on the actual Vault server machine and use localhost to connect to the server.

Log files for troubleshooting purposes:
The Folder Export/Import log can be found at C:\Program Files\SourceGear\Vault Client\VaultExportImport.txt, and the Vault server log can be found at %windir%\temp\sgvault\sgvault.log.