Releasing a PCB 2D-3D Model to a Vault

Old Content - see latest equivalent

Parent article: Vault-Based Domain Models

From a designer's perspective, a vault-based component (Component Item) gathers together all information needed to represent that component across all design domains, within a single entity. It could therefore be thought of as a container in this respect. A 'bucket' into which all domain models and parametric information is stored.

In terms of its representation in the various domains, a vault-based component doesn't contain the domain models themselves, but rather links to these models. These links are specified on the design-side, as part of the source component definition – from which the released Component Item is generated. As such, before you can delve into the process of defining and releasing vault-based components, you must first ensure that all the domain models themselves have been created and released.

This article takes a look at the process of releasing a PCB 2D/3D Component model into the vault so that it can be used in the creation of one or more vault-based components.

PCB Domain Terminology

Before taking a look at the process of releasing a PCB 2D/3D component model, it is worth taking a moment to become familiar with the related terminology involved. In the past, items within a PCB Library have been generically referred to as Footprints, however this term is no longer strictly correct in the present-day context. Altium Designer includes capabilities that allow designers to model both the footprint (land pattern) of the component as well as its 3D physical shape.

The following terminology is used to distinguish elements within the PCB domain:

  • Model – a generic term that refers to any domain-specific representation of a component that is useful when analyzing or working with the component in a specific context.
  • Footprint – a model that refers to the two-dimensional pattern of copper, masks, and overlays that describe the area on the PCB (where the physical component will be mounted).
  • 3D Body – a model that refers to the three-dimensional representation of the physical component to be mounted on the PCB.
  • PCB Component – a complete PCB domain model of the component that includes its Footprint and 3D Body. This can also be more fully referred to as the PCB 2D/3D Component.

Designers are encouraged to adopt a similar vocabulary to ensure minimal confusion between the different descriptive terms.

Creating the Model

A PCB 2D/3D component model within a PCB Library document (*.PcbLib) on the design side is mapped to a PCB Component Item in an Altium Vault. Each release of the library stores the model data into a new revision of that Item.

Firstly, create a new PCB Library file (File » New » Library » PCB Library) and add/draw the 2D footprint as required. Add also additional 3D body information to the footprint if applicable. A single library may contain any number of PCB 2D/3D component models, with each independently linked to a unique Item in the target vault.

Although a single library can contain multiple models, from a version control perspective it is best practice to have one model per library file. This allows you to check out and modify just the models you need to modify, without registering a version change to an entire, single source. A tool to split PCB source libraries into individual libraries, each containing a single 2D/3D component model, is available from the Release Manager – as part of a set of migration tools. Splitting can be performed before or after the symbols have been released to the target vault.

Once the model is drawn as required, save the library.

Example 2D PCB footprint in a PCB Library file.

You can now proceed to release the library. To do so requires the following steps:

  1. Link the PCB Library file to the required target vault, and a specific folder within that vault.
     
  2. Release the model into the next planned revision of the corresponding target Item.

Linking the Library to a Vault

Linking the PCB Library to a vault is performed in the Board Options dialog. Enable the Link To Vault option in this dialog to access link controls.

The Board Options dialog can be quickly accessed by using the File » Link Library to Vault command.

Link the PCB Library to the required target vault, and folder within that vault, using
the Board Options dialog.

Use the Target Vault field to nominate the vault into which you want to store released data for the model within the library. The drop-down associated to the field displays all vaults that you currently have an active connection to. If you have not connected to a vault, click the Vault Admin button to access the Data Management – Vaults page of the Preferences dialog, from where you can make a connection to the required vault as necessary.

Use the Target Folder field to nominate the folder into which the corresponding Item for the model being released will be created. Click the Choose button to access the Choose Folder dialog. This dialog essentially provides you with a folder-specific view into the target vault. Either browse to, and select an existing folder in the vault, or add a new folder. (Using the Show in Explorer button will quickly access the Vaults panel, with the chosen folder made active).

Choose a target folder in which the released PCB Component Item is to be created and reside.

Folder Type

When creating the folder in which to store the model, you can specify the folder's type. This has no bearing on the content of the folder – releasing PCB 2D/3D component models will always result in PCB Component Items. It simply provides a visual 'clue' as to what is stored in a folder and can be beneficial when browsing a vault for particular content. To nominate a folder's use as a container for PCB Component Items, set its Folder Type as altium-pcb-component-library.

Specifying the folder type - its intended use - gives a visual indication of the content of that folder when browsing the vault!

Item Naming Scheme

Another important aspect of the parent folder is the Item Naming Scheme employed for it. This defines the format of the unique ID for each Item created in that particular folder. Several default example schemes are available, utilizing the short-form code for either the folder type or the content type. Using a default naming scheme, the software will automatically assign the next available unique ID, based on that scheme, having scanned the entire vault and identifiers of existing Items.

A custom scheme can also be defined for a folder, simply by typing it within the field, ensuring that the variable portion is enclosed in curly braces (e.g. PCBMODEL-001-{J000}).

The Item Naming Scheme of the parent folder is applied to the unique ID for each Item
created in that folder.

The Item Naming Scheme employed for the parent folder can be changed at any time. The modified scheme will then be applied to any subsequent newly-created Items within that folder.

Item Lifecycle Definition and Revision Naming

Use the Lifecycle Definition and Revision Naming fields (in the Board Options dialog) to choose the type of lifecycle management to be used for the created PCB Component Item, and the naming scheme employed for its revisions, respectively.

Selecting the Lifecycle Definition and Revision Naming schemes.

Observing standard revision naming schemes and lifecycle definitions, across the various types of design item in a vault ensures smooth, consistent management of those items. At the lowest level, it's typical for models to use 1-level revision naming with basic lifecycle management – they’re either ready for design reuse or not!

Verifying the Link is Established

After defining the link to the vault as required, clicking OK in the Board Options dialog will create the link and store it in the PCB Library document. You can view this information at any time, using the Library Options command from the main Tools menu.

At the individual model level, evidence of the link can be seen in the PCB Library Component dialog (Tools » Component Properties), through addition of the Footprint Link region. For a new, unreleased model, this information will become populated once the model is released to the vault.

Evidence that the link to the vault has been established.

Save the library file – the library is now ready to release.

Performing the Release

With the link to the target vault (and folder therein) in place, you can now proceed to release the model in your library. The release process is performed from within the Release Manager dialog.

Release Manager

The Release Manager dialog is accessed using the File » Release To <TargetVaultName> command. This is a modified version of the full Release Manager dialog, the difference being that in this context it is used to release the single, active library document, rather than batch-release multiple libraries in a nominated source folder.

Release source model(s) in the active library document using the Release Manager.

The contents of the library document to be released are listed in the main grid region of the dialog. The grid itself presents all information relating to the link between a source model and its vault-based Item, as well as the actions that will be taken if the source entity is included in the release process. Considering a source model entry in the grid, the following information is presented:

  • Target – this region of the entry provides information regarding the link to the Item, that is either already established (if released already) or will be established (if awaiting initial release). It consists of the target vault, the folder within that vault, and the ID of the Item itself.
  • Current Revision – if the source model has been released previously, this region of the entry provides information about the latest released revision, in terms of revision ID and lifecycle state.
  • Next Revision – this region of the entry provides information about the next revision of the Item that will be created to receive data from a subsequent release of the source model. It reflects the revision ID and the lifecycle state of that revision which, for a new release, will always be in the Planned state.
  • Action – this region of the entry shows the action that will be taken by the Release Manager, for this particular model, as part of the release process. For an entity that has not yet been released, this entry will display Create New Item. The associated Status field is used to indicate the next step to be taken in the process (e.g. Requires Release Preparation) and, once the release process is complete, reflects the result.
  • Notes – the only editable section for a model's entry, fields are provided in which to enter a Comment and Description for the revision of the PCB Component Item that is created in the vault upon release. By default, these are automatically populated with the name of the model, and its Description (where defined).
Having the model name appear as an Item's comment enables quick identification of which model is which, without having to remember any Item IDs! In addition, the use of a Description can be an invaluable aid when searching the vault for a particular PCB Component Item.
  • Enable – this checkbox controls whether the model is included as part of the release process (checked) or excluded from the process (unchecked).

The Document Options region above the grid presents default options when creating new Items in the target vault. The target vault itself cannot be changed here, but you can freely change other information including the target vault folder in which to release and the various schemes employed for Item Naming, Item Revision Naming and Lifecycle Definition.

In terms of Item Naming, what you set here will override whatever was set at the folder-level within the target vault. A wider choice of default naming schemes is presented here, including schemes to create an Item named using the component name specified in the source PCB library:

  • $COMPONENT_NAME
  • $CONTENT_TYPE_CODE-$COMPONENT_NAME-001-{0000}
  • $COMPONENT_NAME-$CONTENT_TYPE_CODE-001-{0000}

Use the associated First Index field to specify the base level Item – the starting point of the assigned Item ID range. If existing Items in the target vault already use the chosen Item Naming scheme, you can leave this index as 0, as the next available index in the scheme will automatically be used.

If any changes are made to the document options using the controls above the grid, the document must be re-analyzed to ensure the correct link and action information is calculated and presented. If this is required, an Alert will display at the bottom-left of the dialog. Pressing the Analyze Document button will refresh the information and remove the Alert.

Preparing the Model for Release into the Vault

Before the model can be released to the target vault, the library document and corresponding Item for the model being released, must first be prepared. To do this, simply click the Prepare Items and Document button, to the right of the Analyze Document button.

On the vault side, the Item itself will be created, with initial revision in the Planned state. If re-releasing to an existing Item, the next planned revision will be created. This is important, so that this Item, and the unique ID assigned to it, are essentially locked-down – so no-one else releasing to the vault can create an Item with this same ID, or release to the same revision of an existing Item, before this release process is finalized.

On the document side, the source library document is saved with the link information. This is the link to the target vault and folder, along with the Item naming, lifecycle definition and revision naming schemes. At the lowest level, the model in the library will store information that links it to the corresponding named-revision of the Item in the vault that will receive and store the release data for it.

Once the preparation phase is complete, the Action-Status field will display Ready To Release.

With the document prepared for release, the Release Items button becomes available – this indicates readiness to proceed with the release.

If releasing from a PCB Library document containing multiple models, and there are models that are not required to be released, ensure their associated Enable checkbox is unchecked at this time.
After preparing the documents, if an attempt to close the Release Manager before releasing is made, a warning dialog will appear. The warning indicates that the link to the new target Item revision – already written to the source library document as part of the preparation phase – will become invalid. It is strongly recommended to proceed with the release at this stage.

Releasing the Model

To go ahead and release the model, click the Release Items button. The Confirm Release dialog will appear, allowing you to review the release actions either at a summary level, or at a more detailed level. If the release actions are correct, proceed to release by pressing OK.

Review and confirm the actions that will be taken by the release process.

Back in the Release Manager dialog, the Action-Status field will display Release Running.... When the process completes, the Action-Status field will change to Release Succeeded – provided the release was successful.

After its release, information regarding the Item that a model is mapped to is displayed in the Footprint Link region of the PCB Library Component dialog. Click the Show in Explorer button to browse the released model directly in the vault using the Vaults panel.

Example showing information about a model's mapped Item in the vault. Access the Vaults panel to browse the released Item directly within the vault.

When releasing a library document containing multiple models, the release process will essentially split the library as part of the release. For each released model, the released data stored in the vault consists of the model definition, saved in its own PCB Library file, named using the model's name. So for a model named D_Schottky stored on the design-side in a library of models called Diodes.PcbLib, the resulting released data will be a single library file named D_Schottky.PcbLib, containing only that particular model (D_Schottky). If you have already split your library document on the design side, and are therefore releasing a library containing a single model only, the release data will simply be a snapshot of that library document.

The released data can be downloaded by right-clicking on the entry for the Item-Revision and choosing the Operations » Download command from the context menu.

Re-releasing the Model

With the source PCB library document linked to the vault and folder therein, re-releasing the model in that library – to take into account any modifications – is a straightforward process:

  1. Make changes to the model as required.
  2. Save the library file.
  3. Use the File »Release To <TargetVaultName> command.

The source library document and linked target folder and Items therein will be analyzed and the Release Manager dialog will present updated link and status information and ready the library and its constituent model for possible re-release. The action for a model that is being re-released now appears as To New Revision.

Note that all entries in the grid will be initially disabled from releasing by default. Use multi-select features and controls on the right-click menu to enable selected entries for re-release, or all entries, as required. Re-release is then a matter of two clicks – one to Prepare Items and Documents and one to Release Items.

Streamlined Re-release Through File-less Editing

Main article: File-less Editing in an Altium Vault

File-less editing frees you of the shackles of separate version-controlled source data. You can simply edit a supported Item type using a temporary editor loaded with the latest source direct from the vault itself. And once editing is complete, the entity is re-released into a subsequent planned revision of its parent Item, and the temporary editor closed. There are no files on your hard drive, no questioning whether you are working with the correct or latest source, and no having to maintain separate version control software. The Altium Vault handles it all, with the same great integrity you've come to expect, and in a manner that greatly expedites changes to your data.

A PCB Component Item can be edited in this way directly from the Vaults panel, or from the Model Links region of a Component Library document, that is itself currently being edited in this manner. In both cases, access to file-less editing is provided through the Edit command on the respective right-click menu.

Clearing the Link to a Released Item

You may need to sever the links between models and their existing vault Items if you require to release again to a new set of Items. For example, if you have previously released but then deleted the Items from the vault, the source library will still have defined links (although invalid as the vault Items would no longer be found). Similarly, if you need to release the source library to a different target vault.

Severing the Link

Severing the link to the vault can be done in two ways:

  1. Disable the Link To Vault option in the Board Options dialog.
  2. Right-click in the grid region of the Release Manager dialog and choose the Clear Vault Links In Documents command.

Doing so will also remove the Footprint Link region from the PCB Library Component dialog.

If you have already released a model, this procedure will effectively cause the source model and released PCB Component Item to lose knowledge of each other.

Re-establishing the Link

If you need to re-establish the original link between the source library document and the released Item in the vault, you will need to perform the following:

  1. Link back to the same vault and folder (containing the original released PCB Component Item). This involves enabling the Link To Vault option again in the Board Options dialog, and specifying the required Target Vault and Target Folder.
  2. Re-link the source model with its original released Item by choosing that Item (and latest revision thereof) from the Footprint Link region of the PCB Library Component dialog. If this is not done, it is possible to release the same source model to a different (and new) Item in the vault!
  3. Save the library document.
Re-establishing the link for each and every model in a source PCB library in this manner can be very time-consuming, especially if the library contains a sizable number of defined models. This can be minimized if the source libraries are split before release. However, breaking the link to the target vault is not advisable and should only be performed if truly necessary.

Releasing Multiple PCB Library Files

Main article: Batch Releasing to a Vault with the Release Manager

When migrating components from existing component management methodologies to the next-generation vault-based component model, releasing PCB Libraries each containing a single model can be a tedious task – especially since release of a single PCB Library file requires that file to be open and active in Altium Designer. This is also the case if changes have been made affecting models across an array of source PCB Libraries, that need to be re-released into a new revision of each target PCB Component Item.

To facilitate the release of multiple libraries to a target vault simultaneously, Altium Designer provides a Release Manager (File » Release Manager). Unlike the streamlined version of this dialog – which is concerned with the active document only – this is the full release 'console'. Use it to batch-release models stored across multiple PCB Libraries in a nominated source folder location.

Release models, stored in one or more source PCB Libraries, using the Release Manager.

 

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