Managing Vault Items with the Item Manager

Altium Designer, in conjunction with the Altium Vault, offers the ability to update components in an existing board design to use components that reside in an Altium Vault. The ‘unmanaged’ components can be individually updated to Vault-hosted ‘managed’ component Items, or batch updated using automated Parameter matching through Altium Designer's Item Manager.

Using a highly configurable Rule system to target suitable Component Item Revisions in the Vault, Altium Designer's Item Manager provides a fast and effective way to convert the current PCB project to one that uses fully managed components from a centralized Altium Vault.

The Item Manager  provides two key abilities in relation to components and sheets of re-usable schematic circuitry in a board design project:

• Migration – firstly, it allows the conversion of a design project from using components and schematic sheets based on traditional unmanaged files to using fully managed vault-based entities (managed components and managed sheets). In this respect it can be thought of as providing an 'convert to Vault data' function.
• Synchronization – secondly, once a design has been 'converted' to using managed (vault-based) Items, the Item Manager provides a simple way to synchronize the Items used in the design to any corresponding source Vault Items that have been updated. In this respect, it can be thought of as providing an 'update from Vault data' functionality.

By way of background, note that an individual component in a design can be updated to a Vault component directly from its Properties dialog in the Schematic Editor. To do so, check the dialog's Use Vault Component option and browse to a suitable Vault Component Item via the button. The selected Component will replace the existing component and models, and update the component Parameters – the dialog's Revision State entry will indicate the component's synchronization status.

A local unmanaged component can be converted to a Vault-based Managed component on an individual basis, or in bulk using the Item Manager.

While this would be a laborious approach to updating all of a design's components to managed Vault components, in even a small scale board design, the Item Manager provides a simple and automated conversion method that uses advanced Parameter matching (Automatching) and a bulk update approach. A typical application of the Item Manager would be to update an existing board design to use Managed Components and Sheets that have been migrated to the Vault from company Libraries.

– See information on the Altium Designer Library Migrator.

Accessing the Item Manager

The Item Manager dialog is accessed from the main Tools menu from an active schematic document (Tools » Item Manager) and presents all components and sheet symbols found in the active board design project.

Select the dialog's lower Unmanaged or Components tab to populate the list of components in the current design. In essence, the left section of the dialog shows component settings of the active project (Current Settings), while the right section lists how they will change (New Settings) when suitable Managed Components in the Vault have been assigned. To view and access Managed Schematic Sheets, select the Sheet Symbols tab.

Access the Item Manager from the Schematic Editor's main Tools menu. The dialog will auto-populate with the current design components (and schematic sheets).

The way in which component data is presented in the Item Manager dialog is highly configurable, based on the data columns that are enabled and/or grouped. This allows the list of design Items and their associated system/user Parameters to be shown in a way that matches specific approaches to component identification – all Item Parameters, such as proprietary company part numbers for example, can be displayed as needed.

Columns

To configure the which columns are presented in the Item Manager, right click in the dialog's column heading area and select Columns » Select Columns from the context menu. The Select Columns dialog will offer all available parameters from both the local design [Current Settings] and the managed Items in the Altium Vault [New Settings]. Simply add an Available parameter column to the currently Selected columns (), or remove a Selected column as required ().

The columns that are shown, and their order, can be configured to suit your Vault/Library systems and preferences.

Grouping

To group the listed Items data by a particular Parameter column, such as Component type category or Schematic document etc, drag the desired column heading entry to the dialog's upper title row (as indicated by the hint text). The Item list will reconfigure to group its entries by the assigned parameter column.

Any data column heading can be dragged to the dialog's top row to group the listed entries by that parameter.

Migrating to Managed Design Items

Assuming that the connected Altium Vault is populated with collections of Managed components and schematic sheets, the current board design project can be converted to using those managed Items where a suitable match is available. The local-to-vault matching can be performed manually, or as an automated process through the Item Manager based on configurable Parameter matching. When complete, the local unmanaged component definitions will be updated to their managed counterparts from the Altium Vault.

Manually Choosing Vault-Based Items

To manually replace a local component (or schematic) with a managed version from the Vault, select its entry in the Item Manager list and then Choose manually from its right click context options. In the following Choose Managed Component dialog, browse and select a suitably matched Managed Item (or specific revision of that Item) in the Vault.

An example of manually choosing a managed component to use as the source for the existing design component in a design.

When the dialog is closed (OK), the selected managed component information will populate the entry's New Settings region in the list. Note that since the entry is now a pending Managed entity, the updated entry is transferred from the listing under the Unmanaged tab to the list under the Managed tab.

Details regarding the chosen managed Item appear in the New Settings region of the grid, listed under the Managed tab.

Automatching Component Items

To automate the process of choosing matching Vault Items, the Item Manager provides a configurable auto-matching capability that attempts to match each unmanaged design component with a managed Component Item in the connected vault. When a match is found, that managed Component Item will be proposed for the update.

The key to the Item Manager's automatic Parameter matching capabilities is the update Rules and Options available in the Item Manager Options dialog, accessed from the Item Manager dialog's button. The configurable Rules determine which component Parameters in the active (local) design are matched to the Parameters of all Managed Components in the selected Source Vault.

Create simple or complex Rules to accurately match local components to suitable Managed Components in the Vault.

How effective these Rules are in achieving a local-to-vault component match will depend upon the available component Parameters, which will be specific to company systems or individual preferences. In the simplest, but perhaps unlikely, scenario the Comment or Component Name parameter entries may match between the local and equivalent Vault components. In the ideal case however, both the local and Vault the components will share a company reference or manufacturer part number parameter.

To create such a part number Rule for example, select and modify an existing Rule (which can also be renamed) or use the button create a new Rule – a Rule must be selected (checked) to be edited. Note that the Local and Vault Parameter selection drop-down lists are independent, which allows differently named parameters to be nominated – in the below example, the local LibReference parameter and the Vault PartRef parameter represent a company part reference number.

Complex, multi-parameter Rules require that all nominated component parameters match those in a Managed Component.

Running a part/reference number matching Rule such as above is likely to create a near complete match between the local and Vault components. With the Rule established, the matching process is initiated by the button in the Item Manager dialog.

The subsequent Automatching Items dialog will indicate positive matches in green text and include a reference to the name of the successful Rule.

An example of achieving a successful local-to-vault match for all components using a single Rule based on a common part number.

When a match cannot be found, the entry will be in red text and a reference included indicating the reason for the error or matching failure – a different or additional Rule will need to be created to achieve a successful match for those components. Also note that any error will be shown in red text, including when a Rule detects more than one Vault Item (component) match. This conflict is regarded as an 'ambiguous' result, and can be resolved in the Item Manager dialog – see below.

A Rule may find more than one match in the Vault, which can be resolved by adding another Rule or by selecting the preferred option.

When the automatch process is complete, close the Automatching Items dialog (OK) to populate the Items Manager dialog with the proposed new component settings. The pending Managed Items that will be applied to matched entries are listed in the New Settings region, under the dialog's Managed tab.

The pending changes to Vault-based Managed Items are detailed in the dialog's New Settings region.

To resolve any ambiguous Items, generally caused by multiple matches, select the Ambiguous Items (or Ambiguous Footprints) tab and make a suitable choice from the Not selected drop down menu in the dialog’s New Settings section – note that multiple matches, and therefore the available choices, can in fact be referencing different Revisions of the same Component Item. When the issue is resolved (no longer classed as ambiguous) the component Item will move to the Managed/Components tab lists.

Where a Rule detects more than one match the Ambiguous Items tab offers that capability of nominating a choice. More than six matches will result in a Rule error.

Advanced Matching Rules

As outlined above, Item Manager Rules establish Parameter matches between the local project Components and Managed Components in the Vault. Any number of Rules can be created, and these work on descending priority basis. If the first (top) Rule fails, then the next Rule is applied – effectively a sequential Boolean OR relationship.

When the Automatching process is run, the State Notes column in the Automatching Options dialog indicates which Rules have failed in finding a match. In this case a different or new Rule is required to more precisely match the available Parameters.

While basic Rules may fail to find a match for all components, more specific parameters Rules can be created to achieve a fully matched result. 

Use the Item Manager Options dialog’s button to create a new Rule, and the associated button to apply multiple Parameter matching conditions. As each Parameter condition is added the Rule becomes increasingly specific, and all conditions need to be satisfied before the Rule match succeeds – effectively a Boolean AND condition.

Taking the example shown here, where (say) the components cannot be matched by part/reference number Parameters, a new Rule can be created to match suitable specifications for the listed unmatched capacitors shown above.

Rules operate in top-to-bottom sequence until a match is found. Multi-parameter Rules must satisfy all conditions for a match.

Update Options

The Item Manager Options dialog provides a range of Item updating options that can be used to further refine the how automatched Managed Components are applied to the current board design.

The Item Manager's Update options provide a flexible way to determine which parameters are updated, and under what conditions.

The options are applied to the current design via the ECO process, and behave as follows:

• Update ‘Lock Designator’ field – When checked, the local component’s Locked state for the Designator field will be overwritten by its state in the linked Managed Component – see the Schematic Component Properties dialog for more information.
• Update ‘Lock Part-ID’ field – When checked, the local component’s multi-part device ID selector’s Locked state will adopt that of the linked Managed Component.
• Update Parameters – Check to allow a component’s Parameters to be updated to those in the linked Managed Component. Enables the below options.
  • button – Open the Library Update Settings dialog – see below.
  • Preserve parameter location – When checked, the position of a visible Parameter in the workspace remains unchanged, rather than reset to the default position of the linked Managed Component.
  • Preserve parameter visibility – When checked, the Visible status of a Parameter remains unchanged, rather than adopting that of the linked Managed Component.

The Library Update Settings dialog includes a list of all available Parameters, for all components, in the current board project (right-click to access mass on/off functions). Those Parameters checked in the list will be updated when a local component is updated to a Vault Managed Component – the behavior of that update is determined by the options outlined below.

Which component parameters are updated can be precisely specified. Right click to checking options.

The Parameter replacement (or addition) behavior is determined by the lower two options in the dialog:

• Library parameters not in sheet – Sets the update behavior when a Managed Component (Library) Parameter does not exist in the local (sheet) unmanaged Component.
  • Add – The Parameter is added to the component during the update.
  • Do not add – The Parameter is not added to the component during the update.
  • Add if not blank – The Parameter is only added to the component during the update if it has valid data (its Value entry is not blank).
• Sheet parameters not in library – Sets the update behavior when a local (sheet) unmanaged Component Parameter does not exist in the linked Managed Component (library).
  • Remove – The existing (local) Parameter is deleted from the component during the update.
  • Do not remove – The existing Parameter is not deleted from the component during the update.
  • Remove if blank – The existing Parameter is deleted from the component during the update if it does not have valid data (its Value entry is blank).

Applying the Update

The proposed changes that have been set up in the Item Manager are applied to the current board design by generating and executing an Engineering Change Order (ECO). Select the range of listed components you wish to update, and then the desired ECO option from the button menu – the options are:

• Generate ECO – use this command to generate and execute an ECO through the Engineering Change Order dialog. Within the dialog, you can browse the actions that will be taken to implement those changes, and disable any actions as required. When satisfied, execute the ECO and the changes will be applied.
• Apply ECO – use this command to directly create and execute an ECO 'quietly' (without the Engineering Change Order dialog appearing).

Changes are implemented through use of an Engineering Change Order (ECO), which can be run quietly, or through a dialog (as shown).

The executed ECO process will update the project components accordingly, which will then be listed in the Item Manager dialog as currently up-to-date Managed Components. Note that the previous icon for each entry () has changed to indicate the reference to a Managed Component ().

The Item Manager showing the new current settings for the design items in the PCB project. Previously unmanaged design components have been fully replaced with managed Component Items from a vault.

In the Schematic Editor, the updated components are linked to their matched Managed Components in the Vault – the active link information will detect a change in the Managed Component's Revision state when/if it is subsequently updated. Access an item's properties dialog to verify the change, by noting the information in the Link to Vault region.

Example showing the successful replacement of an unmanaged component, where the properties dialog reflects the link from the placed instance back to the vault-based Component Item revision.

Synchronizing to Vault Changes

During the course of product development changes are likely to occur in the source (library/vault) components. For example, component models may be updated to a new drawing standard, or component definitions may have been updated to add new parameters. These changes to the source components must be detected and made to flow through to any affected schematic sheets. 

As well as being used to detect and manage components that are currently Not Managed (meaning they are not from an Altium Vault), the Item Manager is also used to detect and manage Items that are Out of date. The Item Manager compares the Items found on the current design against those same Items in the Vault and then flags any differences that are found. Out of date Items can easily be updated, and a report can also be generated.

Detecting when Updates are Required

When the Item Manager is opened it automatically compiles the schematic project, detects and lists all components (indicating if they are managed or not), and then compares the Item-Revision of each managed component on the schematics against the available Revisions of that Item in the Vault. If there are Items that have a newer revision available in the Vault, these are flagged as Out of date in the Item Manager's Revision Status column.

Note the components that have been detected as being Out of Date, select them and then right-click to perfom an Update.

Updating Items

To bring out of date items up to date they must selected, and then the Update to Latest Revision command applied from the right-click context menu. The New Settings region of the dialog will then show the detail of each new Item-Revision. Select the Apply ECO option from the ECO button menu to generate the Change Order and apply the new revision(s) to the components in the design.

Select the out of date Items (using Shift-click selection) and use the Update to latest revision right-click command to update to the board design components.

Note that during a revision update (synchronization), the Item Parameters will be updated as defined by the current Update Options settings in the Item Manager Options dialog (accessed from the Item Manager's button – see Update Options, above.

Item Manager Report

Before committing to a component update or change process in the Item Manager it may be prudent to generate a snapshot of the current listing information using the dialog's Export function. To do this, right-click anywhere in the Item Manager and select Export from the context menu, and then navigate to a suitable location and name the report as required. 

Select Export from the right-click menu to generate a report from the Item Manager.

The report is generated as an HTML file, and presented with the same layout as the current Item Manager display.

The report is generated in an HTML format, and represents a snapshot of the complete Item Manager listing.