Migrating from a Satellite Vault to an Altium Vault Server or Personal Vault

Frozen Content
This article features migration to an Altium Vault Server as the target vault. This is now considered a legacy vault, superseded by the Altium Vault (version 2.0 or later). The same principles of migration can be applied to this later vault technology.
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.

The Altium Satellite Vault Server (or 'Satellite Vault') has been the faithful, sole offering of Altium's Vault Technology since the latter's inception, and the foundational cornerstone of Altium's Design Data Management solution. A server-based engineering content management system that provides an efficient means by which to handle design data in a highly secure, yet readily-accessible manner. And offering a host of features and functionality, including revision and lifecycle management, sharable design content and powerful where-used capabilities.

And the Satellite Vault has played a fundamentally key role in the formulation of Altium's Vault-driven Electronics Design methodology – an approach to electronics design whose central concept is that of designing for reuse, and the explicit directive that all elements in a design must be sourced from an Altium Vault. So the Vault becomes both the destination of released data from the design space, and also the source of design elements for use back in a design –  models that can be reused in a new component, components that can be reused in functional sub-circuits, functional sub-circuits that can be reused in the design of a modular assembly, and then ultimately reusing a modular assembly in a larger design itself.

Altium has since expanded on this existing Vault Technology to offer two, essentially successor flavors of Altium Vault, for use in your overall design data management solution – the Altium Vault Server and Altium Personal Vault  (or Personal Vault). And while you can still connect to, and work with a Satellite Vault, this type of vault will not be supported moving forward. In support of this, a utility is available to migrate the data from your current Satellite Vault to one of these new vault offerings – the Vault Migration Tool.

In this article, we will take a look at the process involved in migrating data from a legacy Satellite Vault into your Altium Vault Server or Altium Personal Vault. Tutorial-like, but not rigidly so, think of this article as more of a conversational 'walk through' of the steps involved – enabling you to ultimately 'jump vault' as it were, and benefit from the current capabilities of, and future enhancements to, these new vault technologies.

Before plunging into the migration process, you should bear in mind that connection to an Altium Vault Server or Altium Personal Vault from Altium Designer is ONLY possible with Altium Designer 13.0 (or later). If you have Altium Designer 10/12 installed, you will only be able to connect to a Satellite Vault.

For detailed information about the Altium Vault Server and Altium Personal Vault, including the installation process for each, refer to the article Altium Vault Technology.

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-<VersionNumber>.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), VaultMigrationTool.sql (providing the smarts of the migration between source and target vault databases) and VaultMigrationTool.ini (which is used to store AltiumLive credentials entered during migration configuration).
  • You also need to have the target vault – Altium Vault Server or Altium Personal Vault– installed on the required computer. The installation must be a fresh install, so that the vault contains no data. You can however define users and groups (for an Altium Vault Server) ahead of migration should you wish.
  • If the target Altium Vault Server or Altium Personal Vault is not installed and running on the same computer as the Satellite Vault, you will need to copy the Data folder (including its Files sub-folder) of your Satellite Vault to that target computer.

For a default installation of the Satellite Vault Server, the Data folder can be found at: \Program Files (x86)\Altium Satellite Vault Server\AltiumVault\Data.

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

Migrating the Data

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

Use the Vault Migration Tool to move your data from a legacy Satellite Vault to an Altium Vault Server or Personal Vault.

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

  • Migrate from Satellite vault
  • Update supply chain information in a Vault Server database to be used with Altium Vault Server 1.1

Ensure that the first of these is enabled (which is the case by default). The second 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.

When migrating data from a Satellite Vault to version 1.1 of the Altium Vault Server, the supply chain information is updated automatically as part of that migration. Only use the Vault Migration Tool to update supply chain information when upgrading from Altium Vault Server 1.0 to Altium Vault Server 1.1. For more information, 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 Satellite Vault can be found. Fields are initially populated with information based on default Vault installations.

  • Source Vault Path – this field is optional. If the source Satellite Vault and target Altium Vault Server/Personal Vault are installed on the same computer, then enter here the path to the Satellite Vault executable folder. For a default Satellite Vault installation, this will be \Program Files (x86)\Altium Satellite Vault Server\AltiumVault. If you have copied the Data folder for the Satellite Vault from another computer, ensure this field is blank.
  • Source Database File – enter here the path to the Satellite Vault database file. For a default Satellite Vault installation on the same computer as the target Altium Vault Server/Personal Vault, this will be \Program Files (x86)\Altium Satellite Vault Server\AltiumVault\Data\EmbFirebirdDb.fdb. If you have copied the Data folder between computers, this will be in the location to which you stored that folder.
  • Source File Repository Path – enter here the path to the Satellite Vault file repository. For a default Satellite Vault installation on the same computer as the target Altium Vault Server/Personal Vault, this will be \Program Files (x86)\Altium Satellite Vault Server\AltiumVault\Data\Files. If you have copied the Data\Files folder between computers, this will be in the location to which you stored that folder.
  • Destination Vault Path – enter here the path to the target vault executable folder. Use the drop-down list to quickly choose the path for a default Altium Vault Server installation (\Program Files (x86)\Altium\DXP Apps Server\Vault) or Personal Vault installation (\Program Files (x86)\Altium\Personal Vault\Vault).
  • 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.

Double-clicking on the Source Vault Path or Destination Vault Path fields will give access to the Select Directory dialog, which can be used to browse to, and select, the required directory.

Provision of your AltiumLive login credentials enables the Vault Migration Tool to access your Satellite Vault, the authentication of which is performed by the AltiumLive-based Identity Service (IDS).

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

Example message stream for a successful migration of Satellite Vault data to a Personal Vault.

When migrating to an Altium Vault Server, a user with the supplied AltiumLive credentials will be added to the list of users having access to that vault. Similarly, if there are any Items in the source Satellite Vault created by other people, then additional users will be created accordingly, based on their separate AltiumLive login credentials. These users will initially be non-administrative.

Controls at the bottom-right 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 connect to your Altium Vault Server or Personal Vault. After successfully connecting through the Data Management – Vaults page of the Preferences dialog, you will notice that the Altium Vault Server/Personal Vault has had its Name and Description changed, using the name and description from the Satellite 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 Satellite Vault after the migration process. The data is not 'moved' as such to the target Altium Vault Server/Personal Vault, but rather a copy of it taken and imported into that target vault. However, since the Globally Unique Identifier (GUID) of the original Satellite 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 Satellite Vault, along with indication that the Altium Vault Server/Personal Vault contains migrated data.

And popping open the Vaults panel quickly verifies successful migration of the data into the target Altium Vault Server/Personal Vault, with folder structure and Items exactly as they were in the source Satellite 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.

Utility Not Run as Admin

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

The utility needs to be run as Windows Administrator!

Target Vault Not Empty

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

The target vault must be freshly installed - devoid of data!

Incorrect Source Vault Path

The optional Source Vault Path is incorrect. While the path entered here is to the Satellite Vault executable, it is used to find the configuration file for the Satellite Vault – Config.ini – located in the \Program Files (x86)\Altium Satellite Vault Server\AltiumVault\_AltiumVaultResources\Private folder for a default Satellite 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 Data folder for the Satellite Vault has been brought across from another computer (i.e. Satellite Vault is not installed on same computer as target Altium Vault Server/Personal Vault), simply remove the entry in this field and use the sub-fields to manually enter the correct paths.

Entering the Source Vault Path incorrectly will mean the config file cannot be located, and therefore the paths to database and file repository cannot be auto-populated.

Incorrect Source Database File Path

The Source Database File path is incorrect and therefore the tool cannot find the Satellite Vault database file, EmbFirebirdDb.fdb.

Example incorrect path for the Satellite Vault's database file.

Incorrect Source File Repository Path

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

Example incorrect path for the Satellite Vault's file repository.

Incorrect Destination Vault Path

The Destination Vault Path is incorrect. While the path entered here is to the Altium Vault Server/Personal Vault executable, it is used to find the configuration file for that vault:

  • Altium Vault Server – the LocalVault.ini file, located in the \Program Files (x86)\Altium\DXP Apps Server folder for a default Altium Vault Server installation.
  • Altium Personal Vault – the LocalVault.ini file, located in the \Program Files (x86)\Altium\Personal Vault folder for a default Altium Personal Vault installation.

This file, among other things, contains the locations of the target vault's database and revision files folder.

Entering the Destination Vault Path incorrectly will mean the config file cannot be located, and therefore the paths to
database and revision files cannot be obtained.

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 the Satellite Vault.

Be sure to enter your correct AltiumLive credentials!

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