Managed Project Templates in an Altium Vault

Now reading version 17.0. For the latest, read: Managed Project Templates in an Altium Vault for version 17.1
Applies to Altium Designer version: 17.0

 

The Altium Vault (3.0 or later) offers the ability to store and manage Altium Designer Project Templates, which can be released directly into Vault where they become available for reuse in future design projects. Project Templates stored in the Vault can include the common document and file types that make up an Altium Designer Project, including additional reference documentation and configuration files.

Within the Vault, a Project Template is hosted as a lifecycle-managed revision of a Project Template Item, which allows administrative control of when that template is ready for use, and by which users or design teams. The managed template availability is exclusively under the command of the Vault’s Environment Configuration service, the Team Configuration Center. This assigns specific configuration data Items, such as stored Project Templates, to defined user groups, so that their Altium Designer work environment is constrained to use only those approved templates.

Release a Project as a Template

There are a number of approaches that can be taken to creating a managed Project Template:

  • A suitable existing Altium Designer project can be released to the Vault, and then edited a later date to fine tune the template configuration and content.
  • A dedicated project can be created, with its content and configuration specifically arranged as a project template, and then released to the Vault.
  • A Project Template Item can be created in the Vault and edited on-the-fly in Altium Designer to add content and set the project configurations. This method is arguably the least intuitive approach, so the focus here is on literally releasing an Altium Designer project to the Vault as a template.

When preparing an Altium Designer Project for release to the Vault as a managed project, it is worth noting that all major files in that project will be become source files in the Project Template. This includes all design documents and the objects or content they contain, and other files held in the project’s host folder – including any common files that are unused. As such, it is worthwhile taking the time to review and fine tune the source project, so that the final Project Template will only contain the files, content and settings required for the desired template.

The advantage of this approach is that a template can contain, if required, a full set of common project files (including PCB OutputJobs), and ratified project/document options, design rules, parameters, units settings, document title blocks, grid setting and much more.

When a project is to become a Project Template, a special [ProjectName] string can be included in its document names. Altium Designer will automatically replace that string with the Name of the new project when the template is used. See below for more details.

To initiate the process of releasing the currently active Altium Designer project to the Vault as a managed, reusable Project Template, select Project » Release to Vault template from the main menu. This will open the Select or create project item for release dialog, where if not already available, the target folder and Project Template Item can be created.

Releasing an Altium Designer project to the Vault as a Project Template opens a Vault Explorer type dialog, where the container folder and target Item are created.
Releasing an Altium Designer project to the Vault as a Project Template opens a Vault Explorer type dialog, where the container folder and target Item are created.

To release a Project to a Vault template revision, you need to be connected to a suitably-licensed Altium Vault and have administrator-level access.

Folder and Type

If a suitable Vault folder is not already available for Project Templates, one can be created or an existing folder’s type changed to reflect its new content.

Use the right-click menu options to add a Project Templates type folder or change an existing folder (via the folder's Properties menu) to the Project Template type. Set the Folder Type, Folder Name and Description in the following Edit Folder dialog.

A folder’s type setting is simply a label, and has no bearing or restriction on the type of content it holds.

With the Vault, a folder's Type setting provides a visual indication of its intended use and what content it is likely to contain.
With the Vault, a folder's Type setting provides a visual indication of its intended use and what content it is likely to contain.

Item Naming Scheme

The folder’s applied Item Naming Scheme will define the format of the unique ID for each Item created in that folder. Using the nominated naming scheme, the software will automatically assign the next available unique ID based on that scheme, while avoiding a naming clash with any existing Items in the Vault.

Several default example schemes are available in the Item Naming Scheme drop-down menu. These use a short-form code for either the folder type (usually PRJT – Project Templates) or the content type (PRJT – Project Template):

  • $CONTENT_TYPE_CODE-001-{0000} – for example, PRJT-001-0001.
  • $CONTENT_TYPE_CODE-001-{A00} – for example, PRJT-001-A01.
  • $FOLDER_TYPE_CODE-001-{0000} – for example, PRJT-001-0001.
  • $FOLDER_TYPE_CODE-001-{A000} – for example, PRJT-001-A001.
Note that in the latter two example formats a new Project Template Item will adopt the host folder type code as a prefix, so if a Project Template Item is created in say, a Generic Folder type, the example ID code for that Item would be GEN-001-0001 or GEN-001-A001.

The Naming Scheme defines how Items within the Folder are automatically named.
The Naming Scheme defines how Items within the Folder are automatically named.

A custom naming scheme can also be defined for a folder, simply by typing it within the Item Naming Scheme field and ensuring that the variable portion is enclosed in curly braces (for example; BasicTemplate-{0000}). Also, the 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.

Create Item

To create a Project Template Item in the new folder, select the Project Item option after clicking the Add an Item link in the dialog’s Item area, or from the right-click context menu. The following Create Item dialog offers all properties settings for the new Item, including Comment and Description fields that will help with quick identification of Project Templates when searching the Vault.

Item post editing is not needed for the process of simply releasing a predefined Altium Designer Project as a vault Project Template, so the Open for editing after creation option can be unchecked – note that this is checked by default.

Creating a new Project Template Item in a Project Template folder type. The Altium Designer project data will be automatically released to the target.
Creating a new Project Template Item in a Project Template folder type. The Altium Designer project data will be automatically released to the target.

When the Create Item dialog is dismissed (OK), the process flow, instigated by the initial 'Release to Vault template' command, will cause the new Project Template Item to be automatically populated with the project data released from Altium Designer.

Lifecycle Definition and Revision Naming

Before completing the Project to Project Template release, check that both the Item’s Revision Naming Scheme and Lifecycle Definition are correctly specified. The Vault’s default settings for Project Template Items are: 1-Level Revision Scheme and Basic Lifecycle, respectively.

Control over which Item types can use a particular lifecycle definition or revision naming scheme can be globally defined and enabled from the Content Types dialog. To access this dialog, select the browse icon in the Revision or Lifecycle field to open their respective Scheme or Definition editing dialogs. Within these dialogs, the Content Types link will open the Content Types dialog list that applies to the currently selected tab (the 1-Level Revision Scheme tab, for example).

The Project Template Item Naming Scheme and Lifecycle Definition field should offer sensible default choices. These can be modified in the Content Types dialog.
The Project Template Item Naming Scheme and Lifecycle Definition field should offer sensible default choices. These can be modified in the Content Types dialog.

Released Project Template

At the completion of the Create Item process the active Altium Designer project will be released to the new Vault Project Template Item as the initial revision, ready for reuse in Altium Designer.

The released Project Template – now a 'managed' template – will contain the core files from the source Project, which can be viewed and accessed through the Vaults panel (DXP » Vault Explorer). These released documents represent the files that will be loaded as constituent parts of the Project Template, when it is applied to a new Altium Designer project.

Altium Designer's Vaults panel can be used to manage and modify released Project Templates.
Altium Designer's Vaults panel can be used to manage and modify released Project Templates.

Edit a Managed Project Template

The new project template can be subsequently edited when necessary by right clicking on its Item Revision entry (in the Vaults panel) and selecting Edit xxx from the context menu (where xxx is the selected Revision’s name).

The Project Template and its constituent document files will open in Altium Designer as a temporary editable project, which is named according to the source Item Revision.

A managed Project Template can be updated in a few simple steps, where it is effectively 'checked-out' to Altium Designer for editing and then checked back in to the Vault as a new Revision.
A managed Project Template can be updated in a few simple steps, where it is effectively 'checked-out' to Altium Designer for editing and then checked back in to the Vault as a new Revision.

When the edits to the temporary template project are complete in Altium Designer, right-click on the project name and select Release to Vault from the context menu. This will release an new template revision to the Vault, named according to the defined Revision Naming Scheme, and then automatically close the temporary Altium Designer template project.

Documents that have been saved during the template editing process are located in temporary local storage, and are correctly included in the new template revision.

The intervening Create Revision dialog allows the addition of relevant release information to the new Project Template Revision.

A Project Template is (re)released to the Vault as a new template revision when edits have been completed in Altium Designer.
A Project Template is (re)released to the Vault as a new template revision when edits have been completed in Altium Designer.

Accessing Managed Project Templates

Managed Project Templates can be applied when creating a new Project in Altium Designer, or when adding a new project through the Vault web interface.

Altium Designer projects

Vault-based Managed Project Templates are available to Altium Designer on a User Role basis, and as determined by the template assignments in the Vault Team Configuration Center – normally under control of Vault Administrators. This service allows specific configuration data Items, such as stored Project Templates, to be assigned to defined User groups, so that their Altium Designer work environment is constrained to use only those approved templates.

Project Templates are added to team Environment Configurations through the Vault browser interface, by first accessing the configuration console (ADMIN » CONFIGURATIONS) and selecting a listed Environment Configuration, or creating a new one (Add Configuration).

In the selected configuration, use the Project Templates drop down menu to assign all available templates in the Vault (All Available Revisions) or one or more nominated templates (Specific Revisions).

In the Configuration, assigning all Project Templates (All Available Revisions) to the nominated User Role(s) will provide Users in that group access to the latest Revisions of all templates. When an Altium Designer user that is a member of the Role signs in to the Vault from Altium Designer, only those Project Templates (in their newest incarnation) will be available for new projects.

Note that locally-stored Project Templates are available when an Environment Configuration has not overridden their use, or when a User is not signed into the Vault.

Alternatively, selecting the Specific Revisions option and clicking the Add button will open a Vault Explorer window, where one or more template revisions can be nominated – simply select the check boxes of the template Revisions you would like to add, and click OK to confirm the selection. Note that any Revision of a Project Template can be nominated with this approach, including those that are not the newest Revision.

Altium Vault projects

Vault-based Managed Project Templates can also be used when creating a new project structure in the Altium Vault itself, via the Vault browser interface.

The Vault-based Templates (depending on User and Item Permissions) are available in the Add project dialog, which is accessed from the  button under the Projects tab.

The newly created Managed Project structure, which can be subsequently edited in Altium Designer, is based on the selected Project Template.

Automated document naming

A valuable feature that becomes available when Altium Designer applies a Project Template to a new design is the automated naming of the template’s constituent documents. This capability is enabled by including a special [ProjectName] syntax in the template document names, which will be replaced by the nominated project Name when the template is used for a new project.

So for example, if a schematic document in a Project Template is named [ProjectName].SchDoc, and that template is then used for a new Altium Designer project called New_Project, then the schematic file created in the project will be named New_Project.SchDoc. Note that the naming string can coexist with other characters, so a template document such as [ProjectName]_Top-level-structure.SchDoc will become a project document named Interface_Top-level-structure.SchDoc in a newly created project that has been named Interface.

To include the preprocessing name capability when creating a Project Template, simply edit the document names accordingly (Save As) before releasing the project to the Vault as a Project Template (or if just saving it locally). Alternatively, open an existing Project Template and edit the document names to include the [ProjectName] string.

When the Managed Project Template is subsequently used for a new project, as dictated by the currently applied Environment Configuration, the project documents will be automatically named as specified in the template.

Note

The features available depend on your level of Altium Designer Software Subscription.

Content