Frozen Content

Parent article: Vault Migration

It is only possible to migrate up to Altium Vault 2.1. If you want to get your data into a later version of the Altium Vault, you will need to migrate to version 2.1 first, and then update to the later version afterwards.

For many designers, their first experience with Altium's Vault Technology will have been through use of an Altium Personal Vault. However, this type of vault is now considered legacy technology. And while a Personal Vault can still be used, it is no longer supported in terms of further development. Therefore to take advantage of the latest vault technology on offer - both now and into the future - requires data to be migrated to the latest Altium Vault.

So the task becomes one of switching from using the legacy Personal Vault, to the Altium Vault. However, with some Personal Vaults holding considerable amounts of data, the last thing a designer needs is to have to release all that data again, duplicating their efforts and distracting them from the design task at-hand! In answer to this, Altium provides a dedicated utility - the Vault Migration Tool. Use this tool to safely and securely migrate the data from your Altium Personal Vault to your Altium Vault.

For detailed information about the Altium Vault, refer to the article Altium Vault.

Pre-Migration Preparation

Before migration can proceed, there are some prerequisite steps that need to be performed – 'pre-migratory' checks, as it were.

  • To access the Vault Migration Tool, you need to first download and run a small executable – VaultMigrationTool.exe. This executable can be obtained by downloading a zip file, available from the Legacy Downloads for Vault Technologies page, and can be saved anywhere on your hard disk. Extract the downloaded zip file, which contains this executable, along with the files VaultMigrationTool.exe.manifest (which ensures the utility is run as administrator) and VaultMigrationTool.sql (providing the smarts of the migration between source and target vault databases).
  • You also need to have the target Altium Vault installed on the required computer. The installation must be a fresh install, and the vault must not contain any data. You can however define users and roles ahead of migration should you wish.
A fresh install of the Altium Vault has a single, empty folder (Default Folder). This must be deleted in order to successfully migrate data to the vault.
  • If the target Altium Vault is not installed and running on the same computer as the Altium Personal Vault, you will need to copy the database and revision files folders of your Altium Personal Vault to that target computer.

For a default installation of the Altium Personal Vault, the database and revision files are stored in the PersonalVaultData folder, which can be found at: \Users\<ProfileName>\AppData\Roaming\Altium\PersonalVaultData.

To successfully migrate between vaults, you must be using the latest version of the Vault Migration Tool (version 1.3.0.7), Altium Personal Vault (version 1.2), and Altium Vault (version 2.0 or 2.1). Ensure you have upgraded your Altium Personal Vault (if not already) from version 1.1 to version 1.2. For detail on how to do this, see Updating the Installation (Personal Vault). To keep existing vault data, be sure to click No when prompted in the Uninstall dialog – otherwise you'll have no data to migrate!

In addition, it is strongly advised that Altium Designer be disconnected from both the source Altium Personal Vault, and target Altium Vault, before proceeding with the migration process.

Migrating the Data

Right-click on the VaultMigrationTool.exe file and elect to Run as administrator. The Vault Migration Tool dialog will appear.

Use the Vault Migration Tool to move data from your Personal Vault to your organization's Altium Vault.

The tool can be used for five different purposes, as reflected by the options available at the top of the dialog:

  1. Satellite vault -> Altium Vault
  2. Satellite vault -> Personal Vault
  3. Personal Vault -> Altium Vault
  4. Update supply chain in Altium Vault Server 1.1
  5. Altium Vault (Firebird) -> Altium Vault (Oracle)

Ensure that the third of these is enabled. The first two options are only of concern when migrating data from a legacy Satellite Vault. The fourth option is only for users who have been working with Altium Vault Server version 1.0 previously. It is run to ensure that the supply chain information – defined in Part Choice List Items – is updated to move from using the Global Part Catalog, to the Local Part Catalog associated to version 1.1 of the Altium Vault Server. And the fifth option is for users who wish to change from using an installation of their Altium Vault (version 2.0 or later) based on using a Firebird database, to one based on using their organization's Oracle database.

As part of migration, part choice lists will be converted and transferred to the target Altium Vault's local catalog service. To skip this, enable the Offline mode option.

For information on migrating from a legacy Satellite Vault to an Altium Vault Server or Altium Personal Vault, see Migrating from a Satellite Vault to an Altium Vault Server or Personal Vault. For information on using the Vault Migration Tool to update supply chain information when upgrading from Altium Vault Server 1.0 to Altium Vault Server 1.1, see QuickGuide - Upgrading to Version 1.1 of the Altium Vault Server.

With the option to migrate enabled, use the various fields in the dialog to specify information required by the migration process. This information primarily relates to installation paths for the source and target vaults, and where the data for the Personal Vault can be found.

  • Source - Personal Vault - this region provides controls for specifying the following information, relating to the source Personal Vault. The text of the region's header will reflect the build number of the current vault.
    • Vault Path – this field is optional. If the source Personal Vault and target Altium Vault are installed on the same computer, then enter here the path to the Personal Vault executable folder. For a default Personal Vault installation, this will be \Program Files (x86)\Altium\Personal Vault\Vault\. If you have copied the database and revision files folders for the Personal Vault from another computer, ensure this field is blank. Double-clicking on the field will give access to the Select Directory dialog, which can be used to browse to, and select, the required directory.
    • Database File – enter here the path to the Personal Vault database file. For a default Personal Vault installation on the same computer as the target Altium Vault, this will be \Users\<ProfileName>\AppData\Roaming\Altium\PersonalVaultData\DXPServer.dat. If you have copied the database folder between computers, this will be in the location to which you stored that folder.
    • File Repository Path – enter here the path to the Personal Vault file repository. For a default Personal Vault installation on the same computer as the target Altium Vault, this will be \Users\<ProfileName>\AppData\Roaming\Altium\PersonalVaultData\Revisions\. If you have copied the revisions files folder between computers, this will be in the location to which you stored that folder.
  • Target - Altium Vault - this region provides controls for specifying the following information, relating to the target Altium Vault. The text of the region's header will reflect the build number of the current vault.
    • Vault Path – enter here the path to the target Altium Vault executable folder. For a default Altium Vault installation, this will be \Program Files (x86)\Altium\Altium Vault\Vault\. Double-clicking on the field will give access to the Select Directory dialog, which can be used to browse to, and select, the required directory.
  • AltiumLive User – enter here the username (Email) element of your AltiumLive login credentials.
  • AltiumLive Password – enter here the password element of your AltiumLive login credentials.

Fields relating to the source Personal Vault and target Altium Vault are initially populated with information based on default installations of those vaults.

Provision of your AltiumLive login credentials enables the Vault Migration Tool to retrieve supply chain information from the Global Part Catalog.

The default paths are used each time the dialog is accessed. The AltiumLive credentials will be stored and applied, so that you don't have to enter them again and again. These are stored in the VaultMigrationTool.ini file, which gets updated whenever either of the fields are changed.

With all required information specified, click the Run button to proceed with the migration. As migration proceeds, messages will be displayed on the tool's progress in the lower region of the dialog. The process completes with the final message "Migration successfully finished".

Controls at the bottom-left of the dialog can be used to copy or save the migration message stream. Use the Copy log button to copy the current content in the message window to the Windows clipboard. Use the Save log button to access a standard Save As dialog. From here, you can determine where, and under what name, to save the migration stream in a standard text file (*.txt). By default, the file will be named MigrationToolLog.txt.

Post-Migration Vault Access

With the migration complete, you can once again sign in to your Altium Vault. From the Data Management – Vaults page of the Preferences dialog, you will notice that the Altium Vault has had its Name and Description changed, using the name and description from the Personal Vault, along with the suffix (migrated). These can of course be changed simply by editing the vault's properties.

You can still connect to the Personal Vault after the migration process. The data is not 'moved' as such to the target Altium Vault, but rather a copy of it taken and imported into that target vault. However, since the Globally Unique Identifier (GUID) of the original Personal Vault is also copied to the target vault, you will not be able to connect to both vaults at the same time, through Altium Designer.

Name and Description are inherited from the source Personal Vault, along with indication that the Altium Vault contains migrated data.

And popping open the Vaults panel quickly verifies successful migration of the data into the target Altium Vault, with folder structure and Items exactly as they were in the source Personal Vault.

Verify successful migration of data through the Vaults panel.

Troubleshooting

The following are some typical causes of the migration process (import of data into target vault) being aborted.

Not Running Migration Tool as Admin

The Vault Migration Tool is not run as administrator. This can happen if you double-click the VaultMigrationTool.exe file, rather than right-clicking and choosing the Run as administrator command.

Target Vault Not Empty

The target Altium Vault is not empty. Even a single folder with no items whatsoever counts as data. The target Altium Vault needs to be a fresh install, with no data.

A fresh install of the Altium Vault has a single, empty folder (Default Folder). This must be deleted in order to successfully migrate data to the vault.

Incorrect Source Vault Path

The optional Source Vault Path is incorrect. While the path entered here is to the Personal Vault executable, it is used to find the configuration file for the Personal Vault – LocalVault.ini – located in the \Program Files (x86)\Altium\Personal Vault folder for a default Altium Personal Vault installation. This configuration file contains the paths to the database and file repository for the vault respectively, enabling the sub-fields to be auto-populated. If using a non-default installation, ensure this path is entered correctly. If the database and revision files folders for the Personal Vault have been brought across from another computer (i.e. Personal Vault is not installed on same computer as target Altium Vault), simply remove the entry in this field and use the sub-fields to manually enter the correct paths.

Incorrect Source Database File Path

The Source Database File path is incorrect and therefore the tool cannot find the Personal Vault database file, DXPServer.dat.

Incorrect Source File Repository Path

The Source File Repository Path is incorrect and therefore the tool cannot find the Satellite Vault file storage directory, \Revisions.

Incorrect Target Vault Path

The Target Vault Path is incorrect. While the path entered here is to the Altium Vault executable, it is used to find the configuration file for that vault – LocalVault.ini – located in the \Program Files (x86)\Altium\Altium Vault folder for a default Altium Vault installation. This file, among other things, contains the locations of the target vault's database and revision files folder.

Incorrect AltiumLive Credentials

Either the Username (Email), Password, or both, have been incorrectly entered. The AltiumLive Identity Service (IDS) does not recognize the invalid Username/Password combination and therefore cannot authenticate valid access to retrieve supply chain data from the Global Part Catalog.

You are reporting an issue with the following selected text and/or image within the active document: