Vault Items_AD

Parent page: Working with an Altium Vault

Within an Altium Vault, each design entity that can be stored, managed, and reused, is represented as a specific type of Item. An Item is uniquely identified within the vault and can contain any number of Revisions, where a revision contains the data for that Item. Each time a change is made to the data contained within a revision - which for most Item types can be edited directly within an associated temporary editor - it is committed (or re-released) into a new revision of that Item, ensuring that no existing revision can ever be overwritten, and thereby ensuring the highest integrity.

Supported Item Types

Different Items are used to store and represent different types of data. One Item could represent a schematic symbol, another a PCB component model, while another could contain the generated fabrication data from a released board design. To declare the type of content an Item (or rather its revisions) will be used to contain, its Content Type property needs to be specified when creating or editing that Item. To put this another way, you are in essence specifying the Item Type.

The following table lists the various Item types (Content types) that can be created manually by a user in an Altium Vault, along with their:

• Associated Folder Type - the purpose made folder type, where available, in which to store Items of that type. This has no bearing on the content of the folder. 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. An Item can be stored in any folder, including the Generic Folder ().
• Content Type Code - the code used when assigning the unique ID to a created Item of that type, and the parent folder's Item Naming Scheme uses the entry $CONTENT_TYPE_CODE.
• Folder Type Code - the code used when assigning the unique ID to a created Item of that type, and the parent folder's Item Naming Scheme uses the entry $FOLDER_TYPE_CODE.

	Item/Content Type		Associated Folder Type	Content Type Code	Folder Type Code	More Info...
	Component		Components	CMP	CMPL	Managed Components
	Footprint		Footprints	PCC	PCBCL	Managed PCB Footprint Models
	Symbol		Symbols	SYM	SSL	Managed Schematic Symbols
	3D Model		3D Models	A3D	A3DL	Managed 3D Models
	Binary File		Binary Files	ABF	ABC	Free-File Storage
	Simulation Model		Simulation Models	SIM	SML	Managed Simulation Models
	Managed Schematic Sheet		Managed Schematic Sheets	SCH	SSC	Managed Schematic Sheets
	Layerstack		Layerstacks	ALS	ALS	Managed Layer Stacks
	Schematic Template		Schematic Templates	SCHDOT	STC	Managed Schematic Templates
	Project Template		Project Templates	PRJT	PRJT	Managed Project Templates
	Component Template		Component Templates	CMPT	CTC	Managed Component Templates
	BOM Template		BOM Templates	XLT	XLT	Managed BOM Templates
	Outputjob		Output Jobs	OUT	OUTC	Managed Output Job Files
	Script		Scripts	ASF	ASC	Managed Scripts
	Altium Designer Preferences		Altium Designer Preferences	PREF	ADPC	Managed Altium Designer Preferences
	Datasheet		Datasheets	DSH	DSH	Storing Component Datasheets
	PCB Assembly Data		Project Catalog	PAS	PRJ	Managed Board Design Release
	PCB Fabrication Data		Project Catalog	PBL	PRJ	Managed Board Design Release
	PCB Project Design		Project Catalog	PDE	PRJ	Managed Board Design Release
	Draftsman Document Template		Draftsman Templates	DFD	DRT	Managed Draftsman Templates
	Draftsman Sheet Template		Draftsman Templates	DFS	DRT	Managed Draftsman Templates

Item Revisions

An Item can have any number of revisions, which are essentially an evolution of that Item over time. A change is made and the new data content is committed/uploaded/released into a new revision. The data stored in each revision of an item is therefore typically different. To identify between these different revisions of an Item, a revision identifier (ID) is used, which in combination with the Item ID creates a unique identifier for each release of an Item. This gives us the Item-Revision.

A full Item-Revision ID therefore simply identifies a specific revision of a parent Item. There will always be at least one revision of an Item (the first release), but there could be many, depending on how many times the data for that Item has been committed/uploaded/released. An important point to make here is that you can only release to a particular Item-Revision once. If there is a change, then a new Item-Revision must be created. This ensures the highest integrity, as the data contained in a given revision can never be overwritten by re-releasing to the same revision. To release again, a new Item-Revision must be used.

The simplest way to grasp the concept of an Item and its revisions is to think of a 'box', into which all the data for that particular revision of that particular Item, is stored. When the Item is released, the data is put into the box, and the box is closed. The Item ID and the Revision ID become labels on the side of that box - they allow instant recognition of what the contents of the box is used for. If the data needs to be updated and re-released, then the Revision ID is incremented, creating a new box.

The Item-Revision 'Box' - labeled with the Item ID and Revision ID. The contents are the data required to build, or represent, that revision of that Item. The act of releasing
closes the box, preventing any other data being released to that revision in the future. The full Item-Revision ID in this case would be: D-820-1001-01.A.1.

The Lifecycle of an Item Revision

Main page: Item Lifecycle Management

Another important aspect of an Item Revision is its Lifecycle State. This is another identifier that can be used to quickly assess what stage that revision has currently reached in its life, and what designers are therefore authorized to do with it. Where the Revision reflects design changes made to the Item, the Lifecycle State reflects the state of the item from a business perspective, such as Planned, New From Design, For Production, Obsolete, and so on.

Initially, an Item Revision will be in the Planned state - ready to receive (and store) the data generated by the applicable commit/upload/release process. Once that process is complete, that revision is closed (data cannot be committed/uploaded/released to that same revision again), and the Lifecycle State is set to the next applicable state. While the data for this Item Revision can not be modified, the Lifecycle State can be changed to reflect just where that Item Revision is, in terms of its useful life.

Altium Designer provides different types of lifecycle management - from basic management, through simple management including states and state transitions, to fully structured management, where the states and state transitions are organized into distinct stages, with a link between those stages and the Revision ID. Based on these different lifecycle management strategies, a number of standard Lifecycle Definitions are defined, from which you can choose to model the state transitions that an Item Revision may undergo over time. There are also definitions that include 'Approval' type states and transitions - where user-defined specific authorities are required, to increment to a given Lifecycle State.

An Item Revision's lifecycle is managed manually, and in accordance with company policies and practices. Consider a revision of a PCB Fabrication Data Item, containing the data to physically fabricate a bare board. Once the development team are happy with it, the Lifecycle State of that revision might be elevated to a state such as In Prototype and, all being well with the subsequently-manufactured prototype, would then proceed to an In Production state. At a later date another revision of the same Item might be needed (another box!) to introduce better functionality. Once released, this second Item Revision would progress through prototyping to production, while the lifecycle of the previous Item Revision passes through deprecation and finally to obsolescence. The point is that the lifecycle information shows how the contents of the 'Item Revision box' can, or rather are, being used.

Example showing the 'life' of an Item Revision. The revision was at one time
authorized to go for prototype and onto production, but subsequently
became deprecated and is now obsolete.

Creating an Item

The Items themselves are created directly within an Altium Vault, and all of the data needed to manufacture/represent an Item is then stored in that vault, against that Item number. Depending on the Item type, an Item can be created manually, or automatically as part of a commit/upload/release process. Vault management, and Item creation from within Altium Designer, is performed through the Vaults panel.

Items are created in an Altium Vault. From within Altium Designer, the Vaults panel provides the interface to your vault.

Once you have defined the required folders, you can proceed to create Items in the vault. To create an Item, select the appropriate folder, then right-click in the Item region of the panel and choose one of the commands from the context menu (or Create Item sub-menu where applicable). Alternatively, if the folder is empty, use the Add an item control in the center of the Item region to access the menu.

Right-click within the Item region of the Vaults panel to access commands relating to Item creation.

The Create Item dialog will appear, providing all controls necessary to fully define the Item.

Specify the details of the new Item in the Create Item dialog.

For many Item types, you have the option to edit and release the applicable design document into the initial revision of that Item, after creation. To do so, simply enable the option Open for editing after creation, at the bottom of the Create Item dialog (which is enabled by default). The Item will be created and the relevant temporary editor will open, ready for you to create the data for that Item. For more information on working with a particular Item type, read its dedicated page, a link to which is provided in the table earlier in this document.

A Word About the Item ID...

An important aspect of the parent folder in which an Item is created, is the Item Naming Scheme employed for it. This defines the format of the unique ID for each Item created in that particular folder. By defining the Item Naming Scheme at the folder level, Items can be created quickly within that folder, while adhering to the correct ID naming scheme. This is especially the case when Items are being created automatically 'on-the-fly', rather than releasing to existing Items that have been manually created directly within the target vault.

Several default example schemes are available, utilizing the short-form code for either the folder type or the content type (refer back to the table earlier in this document for a list of codes). 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.

Alternatively, should there be a need to have full, manual control over the naming of an Item, simply select the [NO ITEM NAMING SCHEME] entry. A unique Identifier must then be defined for an Item as part of its creation. Note that the system will not allow creation of an Item with a duplicated identifier, so manually assigning an identifier requires knowledge of which identifiers have been used.

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

Irrespective of the setting for the Item Naming Scheme at the folder level, you are free to override any automatically determined ID at the Item level. Simply modify any such ID as required, through the Create Item/Edit Item dialog.

Choosing a Scheme for Item IDs

There is an infinite number of possible name/numbering schemes that can be used for Items, the ones shown in images within the documentation are just examples. There are numerous discussions you can read about what is the best numbering scheme to use. Generally, the experts agree that a short, non-significant, numeric-only numbering scheme is best. Non-significant means that there is no information encoded into the numbering scheme, such as the product category, sub-category, location, etc, each new Item is simply issued the next number in the sequence.

The length is important because the longer the identifier, the greater the chance of a human making an error when they record or recall the Item ID. Experience and academic study have shown that that data entry errors increase as the number of characters increase. Seven digits is believed to be the magic number in terms of being easily and reliably recalled by a human. Beyond a certain length errors increase at an increasing rate – at 15 characters, the error probability is close to 100%.

If it is important in your organization to create identity in the Item ID, then a composite identifier could be the answer. In this case a simple alpha/numeric commodity prefix code is recommended. For example, consider the ID D-820-0001. Here the D in the code could denote Design, meaning this is an Item used for designs. In the next 3 digits, the first digit could denote the product category, such as Peripheral Boards, the second and third digits in the block of three could be used to denote bare boards (1X) or assemblies (2X and up). The final four digits in the Item ID are a simple, non-significant, next-in-the-queue type number.

Setting the ID for the Initial Revision of a Vault Item

Changing from an unmanaged design paradigm to a vault-centric, managed one, requires migrating existing data to an Altium Vault. Such data may well have passed through multiple iterations, and have revision numbering assigned that is recognized across the organization. For example, rev.3 of a Magno-Synthetic Digitizer board may well have passed out the door already, with enhancements to be delivered in rev.4. On releasing to the Altium Vault, having an initial revision that started back at 1 would be confusing to say the least - not just within the organization but, more importantly, to its customer base (who are expecting a later version than their current rev.3!).

To this end, Altium Designer provides the ability to manually set the ID for the initial revision of a newly-created Item in an Altium Vault.

Enabling the Feature

To enable this feature, simply enable the Allow manual initial revision Id option, on the Data Management - Vaults page of the Preferences dialog.

Enable the feature as part of your Altium Designer Preferences.

Setting the Initial Revision's ID

With the feature enabled, create the required new Item in the Vault as usual. After creation, right-click on the Item and choose Properties - giving access to the Edit Item dialog. Hover over the Revision ID field and click the  control. The Set Initial Values dialog will appear, from where you can set the ID to meet your requirements. Fields will be provided, as applicable, to modify the various levels of the ID, in accordance with the chosen Revision Naming Scheme.

Set the various levels of the ID (as applicable to the Revision Naming Scheme employed).

Item Revision Naming Schemes

Main page: Item Revision Naming Schemes

To provide the greatest level of flexibility, the Altium Vault comes with a number of pre-defined Revision Naming Schemes, and also supports user-defined Naming Schemes. The Revision Naming Scheme is specified at the vault level, and applied when an Item is created. To specify the naming schemes for a vault open the Data Management - Vaults page of the Preferences dialog, select the vault and click the Properties button, then select Edit Revision Naming Schemes from the drop-down menu. The Edit Revision Naming Schemes dialog will appear.

Revision Naming Schemes are defined and managed in the Edit Revision Naming Schemes dialog.

The revision naming scheme applied is chosen at the individual Item level, when creating an Item. Different Items can therefore have different revision naming schemes assigned to them.

Item Revision Lifecycle Definitions

Main page: Item Lifecycle Management

The Altium Vault also comes with a number of pre-defined Lifecycle Definitions, and also supports user-defined Lifecycle Definitions. The Lifecycle Definition is specified at the vault level, and applied when an Item is created. To specify the definitions for a vault open the Data Management - Vaults page of the Preferences dialog, select the vault and click the Properties button, then select Edit Lifecycle Definitions from the drop-down menu. The Edit Lifecycle Definitions dialog will appear.

Lifecycle Definitions are defined and managed in the Edit Lifecycle Definitions dialog.

The lifecycle definition applied is chosen at the individual Item level, when creating an Item. Different Items can therefore have different lifecycle definitions assigned to them.

Reviewing and Managing the Revision and Lifecycle State

Related page: Working with the Detailed Item View

For a detailed view of the Revision and Lifecycle history of an Item, right click on the Item in the Vaults panel and choose Full Item History from the menu. The Item view (labelled with the Item's ID) will open.

The Item view gives a detailed history of the release timeline of Revisions of the Item, and their Lifecycle state changes.

The view presents a textual timeline, as well as a graphical view of the revisions of that Item, and their lifecycle history. Additional detail that is presented in the view will depend on the type of Item being examined. For example, for a Component Item, the consituent model links are presented, along with parametric information.

The graphical region of the view displays a column for each major Revision (where the associated revision naming scheme has more than 1 level). Within each column are the minor revisions and their Lifecycle state changes. Right-click on a Lifecycle state cell to perform operations including:

• Establishing a new Planned Revision of the Item, in accordance with the Revision Naming Scheme selected for that Item.
• Managing the Lifecycle state for a particular revision of the Item, in accordance with the Lifecycle Definition selected for that Item.
• Viewing Revision properties.
• Publishing release data directly to a nominated publishing destination (for PCB Fabrication Data and PCB Assembly Data Items only).

The lifecycle of an Item Revision can also be browsed and managed from the Vaults panel. Simply change the aspect view for the selected Item Revision to Lifecycle. To access release data, switch to the Preview aspect view.

Access lifecycle and release data for an Item Revision directly through the Vaults panel, using the Lifecycle and Preview aspect views respectively.

State Change and Release Notes

Enhancing the audit trail for Items in an Altium Vault, Altium Designer provides the ability to enter notes when changing the lifecycle state of an Item Revision and, for some Item types, when releasing the source data into planned revisions in the Vault.

State Change Notes

When changing the lifecycle state for an Item Revision in a Vault, use the State change note region of the subsequent state change dialog to enter a relevant note for that change.

Adding a note to explain the change in an Item Revision's lifecycle state.

Release Notes

When releasing source data into a new planned revision of an Item in a Vault, use the Release notes region of the subsequent Release Confirmation dialog to enter a relevant note for that release. This facility is available when re-releasing any Item type that supports the Direct Editing paradigm.

An example of adding a release note during the re-release of a Layerstack Item to a target Vault.

Viewing the Notes for an Item Revision

The notes added for an Item Revision can be viewed in the following places:

• Detailed Item view - view the associated release note, and notes for revision state changes, in the Note column within the Timeline region. For each state in a revision's life, the applicable note (if added) can also be seen within the graphical view of the revision's lifecycle.
• Vaults panel - switch to the Lifecycle aspect view for the Item Revision. For each state in that revision's life, the applicable note (if added) can be seen in the graphical depiction of the revision's lifecycle. In addition, the release note (if added) is presented in the Note column, within the main Item region of the panel (you may need to enable the display of this column, and also be viewing the folder in Classic View mode).

Viewing the notes associated to revisions of a Component Item.