Migrating Existing Libraries to Your Connected Workspace

Now reading version 2.1. For the latest, read: Migrating Existing Libraries to Your Connected Workspace for version 4
Applies to NEXUS Client version: 2.1

This documentation page references Altium NEXUS/NEXUS Client (part of the deployed NEXUS solution), which has been discontinued. All your PCB design, data management and collaboration needs can now be delivered by Altium Designer and a connected Altium 365 Workspace. Check out the FAQs page for more information.

 

Parent page: Working with Managed Components

Altium NEXUS, in conjunction with your managed content server, provides a streamlined process to quickly migrate your existing libraries to that Server. The GUI to this process – the Library Migrator view – presents an intuitive flow that takes selected libraries, and migrates them to the managed content server to which you are actively signed in. 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 managed components, and the many benefits that such components enjoy (high-integrity, lifecycle management, centralized storage and management, where-used functionality, ease of design reuse). And while the migration process can be configured – giving you enhanced control over how that migration is performed – you can 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 (managed components that have assigned part choices), with all referenced domain models (schematic symbols, PCB footprints, Simulation Models) and parametric information. Component templates can even be created, and used to create those managed components. 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.

While migration may seem daunting, the defaults have been defined to enable you to get your collection of managed components without having to change a thing – start the process and then design with the Migrator's results. The system conducts and handles a number of validations, for example to ensure no duplicate IDs for the resulting managed 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 graphical interface to the component migration process is the Library Migrator view, which is accessed by choosing the File » Library Migrator command from the main menus – available when signed in to an Altium Managed Content Server.

Accessing the Library Migrator view – the user interface to the component migration process.
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).

File-based (unmanaged) libraries are made available to the Library Migrator through a number of mechanisms:

  • By default, all loaded and supported libraries will be enabled ready for migration. These include project libraries, installed libraries, and libraries found along the specified search paths.

    You can view and manage the currently installed file-based libraries in the Data Management – File-based Libraries page of the Preferences dialog.

    If you wish to access file-based unmanaged libraries in the Components panel, they can be enabled in Advanced Settings dialog available from the  button on the System – General page of the Preferences dialog. Check the Legacy.UnManagedLibraries option to enable access to file-based (unmanaged) library components in the panel, and to also enable access to the Available File-based Libraries dialog from the File-based Libraries Preferences option on the panel's  button menu. You will need to restart Altium NEXUS for the setting change to take effect.

  • Libraries files can be added for migration from the  button in the Library Migrator.
  • Library files can be dragged and dropped from a Windows folder onto the migrator's main libraries listing area.

To successfully migrate a Schematic Library (SCHLIB) to the server, the Library Migrator must be able to locate Models that are linked to that library, such as component footprints in a corresponding PCB Library. This requires that the related model Library is installed – see Data Management - File-based Libraries.

Alternatively, if you do not wish to install multiple model libraries, you will need to ensure that the model source library is specified for components in the Schematic Library, and the libraries are located in the software's default library path. See the below collapsible section for more information.

Note that it is not necessary, or even desirable, to migrate a PCB Library along with its Schematic Library counterpart, since the required model migration and linking will be performed by the Library Migrator itself. The migration process identifies, locates and transfers the correct model(s) for each component to create a unified managed component in the target server.

With the libraries required to be migrated selected (checked or unchecked) in the list, click the   button at the bottom-right of the view to proceed to the next stage.

  

Libraries are listed in alphabetical order.

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

The Split option associated with each library entry is used to separate monolithic libraries – those that contain multiple types of component – into individual, virtual sub-libraries that correspond to each component type. These are then configured for migration in the same way as conventional single-type libraries. Click the Split option to invoke the component type extraction/grouping process, and if required use the following Merge command to revert the library back to its single/monolithic state.

The migrator automatically detects a Type for each library component based on the presence of key string values in the component Designator, Description or Comment, etc – for example, a Designator of R? or a 'Resistor' string in the Description indicates that component type. All components detected as that type are grouped as a Type sub-library.

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:

The current migration configuration settings can be saved for reuse while in the Configuration stage by selecting File » Export » Library Migration Config from the main menu. The configuration is saved as a *.lmcfg file, which can be restored during a subsequent Library Migration process when at the Configuration stage – choose the File » Import » Library Migration Config command and select a saved configuration file to load that setup.

With migration settings configured for libraries as required, click the   button at the bottom-right of the view to move to the following Preview stage. Alternatively, select the Migrate option from the button's drop down menu to bypass the Preview step and proceed directly to the Migrate stage.

Stage 3 – Preview

This stage of the migration process provides a preview of the content that will be created in the managed content server, 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 Server as a result of the migration.
The Preview stage of the migration process allows you to see, in greater detail, what exactly will be created in the Server as a result 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 Server, 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 Server folder. The region is further sub-divided into two:

  • Upper Region – presents a listing of all Component Items that will be created in the Server. For each component, its ID, Comment, Description, and Component Type are 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, 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 click the  button to access and use the Component Type dialog with which to do so.

Similarly, you can change attributes of user-defined parameters on-the-fly too. 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), 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.
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 become a defined part choice for the created Component Item.
Example supply-chain solution associated to the selected component, that will become 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). All of these models will be items in the Server in their own right. Models may be created specifically for the component, under sub-folders, or may be referenced from elsewhere in the Server, 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.
Example models that will be referenced by the selected component.

  • Datasheets – lists any links that have been extracted from the currently selected library source component. These are typically URLs for the component manufacturer's website, and one or more links to PDF reference material such as component datasheets. The datasheet links are included as clickable web reference parameters in the migrated server component, while any local file-based references are migrated to be stored with the component as the indicated server item – by default, the datasheet items will be found in a Datasheets subfolder of the component folder.

Example links that will be referenced by the selected component.Example links that will be referenced by the selected component.

Previewing Issues

While previewing the components and related entities that will be created in the Server, 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, or that simulation parameters will not be migrated as component parameters.

Issues are flagged in the following places:

  • At the folder level, 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, when the affected component is selected.

Flagging issues and providing details of those issues.
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   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 Server. 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 click to continue.
  • If there are components with defined simulation parameters, you will be alerted that such parameters will not be migrated as component parameters. Again, you can cancel the migration at this point, or 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.

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.
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 Server (depending on the migration configuration settings/options):

  1. The general folder structure is created.
  2. 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.
  3. Component types for each library involved in the migration are created, where needed.
  4. 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:

  1. The component list to skip is selected – those components that cannot be migrated due to an existing issue.
  2. The component list to migrate is selected – those components that can be migrated without issue.
  3. The library folder structure is created within the Server, consisting of a component folder and folders for each involved model type. Model folders are created once under a generic sub-folder named Models.
  4. The model libraries are then released, creating the Symbol Items, Footprint Items, and Simulation Model Items (only where existing models are not available for reuse).
  5. The Component Items themselves are then created.
  6. Folder attributes are then set for the various folders.
  7. A saved search item is created.
  8. 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 Server, 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 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), and CSV files (*.csv).

An example migration report, exported into Excel format.
An example migration report, exported into Excel 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 Notepad to be saved as a txt file.
An example illustrating a portion of a migration report copied to the clipboard, then pasted into Notepad to be saved as a txt file.

That's it – with your components migrated, you can close the Library Migrator view and begin designing with your new set of managed components, or click the button to start a fresh library migration session.

Browsing Migrated Components

Browse your migrated components from the Components panel or for accessing all managed server content, the Explorer panel.

By clicking the  button, at the bottom-right of the view when the Library Migrator is presenting the migration report, you can quickly gain access to the Explorer panel. You will be taken to the first component, in the first migrated library.

Viewing the migrated components, directly in the managed content server, courtesy of the Explorer panel.
Viewing the migrated components, directly in the managed content server, courtesy of the Explorer 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.
Viewing the Component Templates, created as part of the migration process, and used in the creation of the components themselves.

If for some reason – such as an unsatisfactory migration result – you wish to delete a collection of components, those selected in the Explorer panel can be cleanly removed by choosing the Delete Components and Models option from the right-click content menu. Along with the selected components, their associated models also will be deleted (if not used by other components). This feature is available to users with server Administrator privileges.
Content