Altium Designer, in conjunction with Altium Vault (3.0 or later) provides a streamlined, simple process to quickly migrate your existing libraries to an Altium Vault. The GUI to this process - the Library Migrator view - presents an intuitive flow that takes initial selected libraries, and migrates them to a target Altium Vault. Catering for all types of libraries, relating to older component management methodologies - SCHLIB, PCBLIB, INTLIB, DBLIB, SVNDBLIB - the Library Migrator is the perfect solution to quickly building your company's set of vault components, and the many benefits that such components enjoy (high-integrity, lifecycle management, centralized storage and management, where-used functionality, ease of design resuse). And while the migration process can be configured - giving you enhanced control over how that migration is performed - at its most simplistic, you can simply accept the default settings and set the migration in motion within a matter of clicks.
What gets Migrated?
All information that is present in an original source library is migrated, in order to arrive at a folder of unified components (vault components that have assigned part choices), with all referenced domain models (schematic symbols, PCB footprints, 3D Models, Simulation Models), and parametric information. Component templates can even be created, and used to create those vault components. And if your original components have multiple PCB footprints defined, you can rest assured that the Library Migrator will bring those models across, and keep the current default footprint too.
And if you only work with PCB libraries - your only concern is PCB layout - then the Library Migrator supports migration of just those libraries only.
And while migration may seem daunting, the defaults have been defined to enable you to get your collection of vault components without having to change a thing - start the process and design with the fruits of the Migrator's labor. The system conducts and handles a number of validations, for example to ensure no duplicate IDs for the resulting vault components, or to ensure no duplicate models or component templates are created, and that such entities are reused across (linked to) components where needed. And if issues do arise, the system flags them, with suggestions on how to resolve those issues, aiming to get the migration back on track as quickly, and as smoothly as possible.
Migration of pin mapping information (for simulation models) is not currently supported.
Accessing the Library Migrator
The migration functionality is delivered through a purpose-made extension - the Library Migrator extension.
The Library Migrator extension.
The Library Migrator can only be accessed, provided the Library Migrator extension is installed as part of your Altium Designer installation. This extension is installed by default when installing the software, but in case of inadvertent uninstall, can be found back on the Purchased tab of the Extensions & Updates page (DXP » Extensions and Updates).
The graphical interface to the component migration process is the Library Migrator view, which is accessed by choosing the View » Library Migrator command from the main menus (from any document editor).
Accessing the Library Migrator view - the user interface to the component migration process.
The Migration Process
The migration process is a staged flow, with the entries on the left-hand side of the Library Migrator view showing you at-a-glance, which stage you are currently at.
Stage 1 - Select Libraries
This stage of the release process is where you specify the libraries that you wish to migrate. Library types that can be migrated are:
- Schematic Library (*.SchLib).
- PCB Footprint Library (*.PcbLib).
- Integrated Library (*.IntLib)
- Database Library (*.DBLib).
- SVN Database Library (*.SVNDBLib).
By default, all supported libraries found within the Available Libraries for the active/focused project, will be loaded and enabled ready for migration - so all project libraries, installed libraries, and libraries found along specified search paths.
Supported libraries, found in the list of libraries available to the active/focused project, will be added and selected for migration by default.
You can also add further libraries to the list of libraries to be migrated. This can be done in a couple of ways:
- Drag and drop selected libraries directly from your Windows File Explorer onto the Library Migrator's main library listing area. The libraries will be added to the migration list.
- Click the Choose from File button, then use the Open dialog to browse to, and select, the required libraries. After clicking Open, the libraries will be added to the migration list.
Libraries are listed in alphabetical order.
With the libraries required to be migrated selected in the list, click the Next button at the bottom-right of the view.
Stage 2 - Configure Migration
This stage of the migration process loads the component list ready for migration, and presents optional controls for configuring the migration.
The migration process has been built to be as simple and streamlined as possible. Accepting the defaults and proceeding with the migration is all that is needed, with no additional configuration required by the user. However, should you wish to have more control over the migration process, then use this page to set up various options - either for all libraries involved in the migration, or on a per-library basis.
An example of accessing the controls to configure the migration for a specific library, in this case Crystals.IntLib.
The page is divided into the following two key regions, with a third region dedicated to providing a preview of the resulting folder structure that will be created/used.
Source Libraries
This region lists all of the libraries involved in the migration process. Select a library to access and configure settings specifically concerned with the migration of that library's components.
Select the <All Libraries> entry to access Component Settings that can be applied to all libraries. Only those settings that are shared by all libraries selected for migration will be presented.
Component Settings
This region of the page presents all settings that can be configured, specifically for the selected library.
At any time, you can rewind to use the default settings, by clicking the Reset to Default link, which appears to the right of the source library entry whenever a change to a setting has been made.
The following collapsible sections look at the various settings available:
Component Type
Use this field to specify the type of component stored in the library. The Library Migrator will try to automatically determine the component type, based on the name of the source library (or table within a Database library). So if the library is named Crystals.IntLib, the Component Type will be set to Crystal & Oscillator. You also have the following choices to craft the component type yourself:
- Choose [LibraryName] from the drop-down, to set the component type to be the name of the library.
- Choose [Parameter.Component Type] from the drop-down, to set the component type to be the type defined in the source component's Component Type parameter (which can be Standard, Mechanical, Graphical, Net Tie (In BOM), Net Tie, Standard (No BOM), or Jumper).
- If your components use any of the following defined parameters: Category, Component Category, or SubType, then entries will be available from the drop-down - [Parameter.Category], [Parameter.Component Category], and [Parameter.SubType] - to set the Component Type to the value for that parameter.
- Click the button at the right of the field to access the Component Type dialog. Use this dialog to choose an existing component type, or create and assign a new one.
- Directly enter the required component type.
- For a DBLib/SVNDBLib, you can also choose [TableName] or [LibraryName]\[TableName].
Where the Component Type cannot be detected automatically, the default is to use [LibraryName].
This field is not applicable when migrating a source PCB Library.
Folders
Use this field to specify the parent folder in the target vault, into which all components in the source library will be migrated, and below which all child folders, containing associated domain models, will be created. You have the following choices available to you:
- Choose Components\[ComponentType] from the drop-down (which is set by default) to have the folder created under a top-level Components folder, and whose name is based on the entry in the Component Type field above.
- Choose Components\[LibraryName] from the drop-down to have the folder created under a top-level Components folder, and whose name is that of the source library itself.
- Click the button at the right of the field to access the Choose Folder dialog. Use this dialog to select an existing folder into which to migrate the source library's components, or create a new folder on-the-fly.
- Directly enter the path to the required folder - either existing or not.
As you change the entry, the resulting folder structure can be seen in the dynamic Folder Structure Preview region to the right.
As you change the entry in the Folder field, the Folder Structure Preview region will update accordingly.
Not only does the Folder Structure Preview show where the migrated components will be stored, for each source library included in the migration, but also how many components (shown in brackets) will be created in those folders.
Component Template
Use this field to determine whether or not a component template is to be created. By default, a new component template will be created and associated with the folder of components, and used in the creation of all Component Items in that folder. Use the drop-down field to select from the following:
- Create new - create a new component template for the source library.
- Do not create - don't create a component template for this library.
- Same as <LibraryName> - choose this entry to use the same component template being created for another source library. There will be an entry in the menu for each of the other source libraries (SchLib/IntLib/DBLib/SVNDBLib) being migrated.
This field is not applicable when migrating a source PCB Library.
Parameter Mapping
This grid presents all parameters defined across the components in the source library, and allows you to map them to parameters required for the components when they are created in the vault (either directly, or via a component template if specified for use). The parameters are sorted alphabetically, with the vault system parameters (ID, Comment, and Description) at the top of the list.
Points to be aware of when working with the grid:
- For the Vault Parameter ID, the Source Library Parameter is set to <Auto>. This results in component IDs automatically created based on the Naming Template specified for Component (at the bottom of the settings region), which is in the format $CONTENT_TYPE_CODE-<xyz>-{0000}, with the central portion (<xyz>) unique to each migrated library. This gives components with IDs like CMP-005-0000, CMP-005-0001, CMP-005-0002, and so on. This can be changed to use any parameter in the source library to create the ID - available from the drop-down.
- You can change the name of the parameter to be created on the vault-side, simply by changing the entry in the Vault Parameter field directly.
- You can skip the migration of a parameter - specifying that it not be created for the migrated components in the vault. Do this either by unchecking the associated checkbox for a parameter entry, or by choosing the <Skip> entry form the drop-down for the Source Library Parameter field.
- With the exception of the system parameters (ID, Comment, Description), you can change the type of a parameter - allowing you to create unit-aware parameters for the components in the vault (via an applicable component template). Simply use the drop-down associated with the Type field to choose the required unit.
- Use the checkbox at the top-left of the mapping grid to quickly disable (skip) all component parameters, with the exception of ID, Comment, and Description.
Supplier Link parameters - Supplier n/Supplier Part Number n - will be disabled (skipped) by default. The Part Choices for the created vault components will be created from this information automatically.
Only the ID, Comment, and Description parameters are applicable when migrating a source PCB Library.
Part Choice Fields in Source Libraries
This section allows you to specify parameters that have been used to specify manufacturer part information, when you do not use Supplier Links. Simply click the Add button, then specify the Manufacturer and Manufacturer Part Number parameters that you assign to your components in the source library. The drop-down fields present all parameters detected across the components in the source library.
The Library Migrator automatically suggests Part Choice Fields based on the most common names used, including:
- Manufacturer [1|2|3]
- MFG 1|2|3
- Manufacturer Part Number [1|2|3]
- Manufacturer PN
- Manufacturer_PN
- Manufacturer 1 Part Number
- MPN
- PartNum
- Part No
This section is not applicable when migrating a source PCB Library.
Naming Templates
This section allows you to define the naming templates applied when creating the various entities associated with creation of a vault component. The defaults are:
- Component - $CONTENT_TYPE_CODE-<xyz>-{0000}
- Component Template - $CONTENT_TYPE_CODE-{0000}
- Symbol - $CONTENT_TYPE_CODE-<xyz>-{0000}
- Footprint - $CONTENT_TYPE_CODE-<xyz>-{0000}
- Simulation - $CONTENT_TYPE_CODE-<xyz>-{0000}
<xyz> is a 3-digit number that is unique to each migrated library.
Templates can be changed to suit your requirements - ensuring that the variable portion is enclosed in curly braces.
With migration settings configured for libraries as required, click the Next button at the bottom-right of the view.
Stage 3 - Preview
This stage of the migration process provides a preview of the content that will be created in the Altium Vault, flags any issues, and allows any last minute changes to component types, parameter names, and parameter types.
The Preview stage of the migration process allows you to see, in greater detail, what exactly will be created in the vault as a reult of the migration.
The preview is essentially divided into two key regions:
Folders
This region, on the left, presents the folder structure that will be created/used in the vault, and is the same as the Folder Structure Preview presented when configuring the migration in the previous stage of the process. Click on a folder entry to load its components in the region on the right.
If there are any issues with components in a folder, a visual indication is given to the right of the folder's name. Read more about issues detected during the preview in the section
Previewing Issues.
Components
This region, on the right, presents the components that will be created in the selected vault folder. The region is further sub-divided into two:
- Upper Region - presents a listing of all Component Items that will be created in the vault. For each component, its ID, Comment, Description, and Component Type is shown, along with all user-defined parameters from the original source library. Should you need to change the Component Type for one or more components, simply select them in the list, then right-click and choose the Change component type command from the context menu. The Change Type dialog will appear. Use this to enter a type directly, or access and use the Component Type dialog to do so.
Similarly, you can change attributes of user-defined parameters on-the-fly to. To rename a parameter, right-click over the column for that parameter and choose the Rename parameter command from the context menu. Use the Rename Parameter dialog that appears to change the name as required. And if you need to change the parameter's type (to make it unit-aware), simply choose the Change parameter type command from the context menu. Set the required type from the Change Type for Parameter dialog accordingly.
The components that will be created in a folder, along with their parametric information. Commands on the right-click context menu cater for last minute changes, such as
changing the type of a parameter (shown), renaming a parameter, and changing the component type.
- Lower Region - presents information relating to the chosen component in the upper region, across the following tabs:
- Details - lists any issues found for the component, such as footprint model not available in the source libraries, or if pin mapping information is defined for a linked simulation model, a caution that this is not supported for migration. See Previewing Issues for more information.
- Part Choices - if supplier information was defined for the original source component, through supplier link parameters (Supplier n/Supplier Part Number n) or text-based manufacturer/manufacturer part number parameters, then this tab will list those supply chain solutions.
Example supply-chain solution associated to the selected component, that will becoame a defined part choice for the created Component Item.
- Models - this tab lists the domain models that will be referenced by the created Component Item (Schematic Symbol, PCB Footprint Model, Simulation Model, 3D Model). All of these models will be items in the vault in their own right. Models may be created specifically for the component, under sub-folders, or may be referenced from elsewhere in the vault, if already created (or going to be created). The system avoids duplication of models, instead reusing a model between multiple components.
Example models that will be referenced by the selected component.
Previewing Issues
While previewing the components and related entities that will be created in the vault, the Library Migrator also flags any issues. Two graphical icons are used to do this:
- - an error. A problem with the original component in the source library will lead to unsuccessful migration of the indicated component. An example might be that the referenced footprint model is not available.
- - a warning, or caution. The migration of the component will proceed, but not fully for some reason. An example is the caution that the migration of pin mapping data is not supported.
Issues are flagged in the following places:
- At the folder level, simply to indicate there are issues with components therein.
- At the component level, with the appropriate icon to the left of a component's entry.
- At the detailed level. Issues are listed on the Details tab, with the affected component selected.
Flagging issues and providing details of those issues.
Catching issues at the preview stage allows you to go back to the source libraries and make any required changes that will ensure successful migration.
Components with errors will be skipped, and therefore not migrated.
Once you are comfortable that all is in order, you can proceed with the actual migration itself, by pressing the Migrate button at the bottom-right of the view.
Stage 4 - Migration
This stage of the process involves the actual migration of the components to the vault. The system performs a final set of checks, including:
- If there are any components with errors (), you will be alerted that those will be skipped (and how many). You are given the option to cancel the migration (and resolve those issues), or click to continue with the migration of those components remaining, and that can be migrated.
- If you have components referencing simulation models with defined pin mapping, you will be alerted that migration of pin mapping is not supported. Again, you can cancel the migration at this point, or simply click to continue.
The migration process then proceeds, with progress displayed graphically through a progress bar, and in detail through a report that shows you exactly what is happening at each point in time. In addition, the Elapsed Time is shown, along with an estimate of the Remaining Time until the migration process fully completes.
You can stop the migration process at any time by clicking the Stop button, at the bottom-right of the view.
An example migration in action. You are kept informed of progress and given detailed information of what the Library Migrator is doing at every stage of the process.
The initial flow of the process involves the following elements being created in the vault:
- The general folder structure is created.
- The component template folder is created, that will house all Component Template Items created for the source libraries. This is: Managed Content\Templates\Component Templates.
- Component types for each library involved in the migration are created, where needed.
- Component templates for each library are then released into Component Template Items, within the component template folder.
For each source library included in the migration process, the following flow is then followed:
- The component list to skip is selected - those components that cannot be migrated due to an existing issue.
- The component list to migrate is selected - those components that can be migrated without issue.
- The library folder structure is created within the vault, consisting of the component folder and sub-folders for each involved model type.
- The model libraries are then released, creating the Schematic Symol Items, PCB Footprint Model Items, 3D Model Items, Simulation Model Items (only where existing models are not available for reuse).
- The Component Items themselves are then created.
- Folder attributes are then set for the various folders.
- A saved search item is created.
- Supply chain information is then migrated, creating the associated part choices for the released components.
The final act of the migration process is to create an 'Item Manager rule'. This creates the necessary auto-mapping, so that once your components have been migrated to the vault, you can then migrate your existing designs to use those components, using the Item Manager, without any additional effort.
Stage 5 - Report
This is the final stage of the process, providing a detailed report (essentially the completed report that could be seen in real-time during the Migration stage).
The final, detailed report for the migration.
The right-click context menu provides the following commands:
- Export to file - use this command to export the entire report. The Save As dialog allows you to specify where, and with what name, the report is saved. Supported formats for export are: Excel files (*.xls; *.xlsx), HTML files (*.html), PDF files (*.pdf), Text files (*.txt), CSV files (*.csv).
An example migration report, exported into xls format.
- Copy to clipboard - use this command to copy the currently selected rows of the migration report, to the Windows clipboard, for pasting into an external application.
An example illustrating a portion of a migration report copied to the clipboard, then pasted into an Excel file.
That's it - with your components migrated, you can simply close the Library Migrator view. Now you can enjoy designing with your new set of vault components.
Browsing Migrated Components
Browse your migrated components from the Vaults panel - your portal to any connected vault.
By clicking the Show in Vault Explorer button, at the bottom-right of the view when the Library Migrator is presenting the migration report, you can quickly gain access to the Vaults panel. You will be taken to the first component, in the first migrated library.
Viewing the migrated components, directly in the target Altium Vault, courtesy of the Vaults panel.
And don't forget the Component Templates that were created, and which are used in the creation of those components. These can be found, as mentioned previously, in the Managed Content\Templates\Component Templates folder.
Viewing the Component Templates, created as part of the migration process, and used in the creation of the components themselves.