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

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.

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.

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.

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

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

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.

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.

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.

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.

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.

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.