Working with Items in a Workspace Connected to Altium Designer

Within a connected Workspace, each design entity that can be stored, managed, and reused is represented as a specific type of Item. To support the need to be able to update an Item over time, what is actually stored in the Workspace is a series of Item Revisions that are specific revisions of that Item whose name is based on the chosen Revision Naming Scheme. Each new Item is created in a folder and once you have defined the required folders within a Workspace, you can create new Items in the selected folder in the Item region of the Explorer panel.

Supported Content 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 content types (Item types) that can be created manually by a user in a connected Workspace, along with their:

• Associated Folder Type – the purpose-made folder type, where available, in which to store the content 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 Workspace for particular content. The content can be stored in any type of folder, including the Generic Folder.
• Content Type Code – the code used when assigning the unique ID to a created Item of that content 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 content type, and the parent folder's Item Naming Scheme uses the entry $FOLDER_TYPE_CODE.

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 saved/uploaded/released into a new revision, ensuring that no existing revision can ever be overwritten, and thereby ensuring the highest integrity. 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 saved/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 format of a revision's ID is determined by the Revision Naming Scheme employed for the parent Item. The specific format used in a scheme is configurable and will depend on the needs of each organization.

State Change and Release Notes

Enhancing the audit trail for content in a Workspace, Altium Designer provides the ability to enter notes when changing the lifecycle state of an Item-Revision and, for many content types, when releasing the source data into planned revisions in the Workspace.

State Change Notes

When changing the lifecycle state for an Item-Revision in a Workspace, 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 Workspace, use the Release notes region of the subsequent Create Revision 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 to a target Workspace.

Viewing the Notes Associated with Revisions of an Item

The notes added for any revision of an Item 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.
• Explorer panel – switch to the Lifecycle aspect view tab for a selected Item-Revision. For each state in a revision's life, the applicable note (if added) can be seen in the graphical depiction of the revision's lifecycle. In addition, view the associated release note, and note for latest revision state change, in the Note column, within the main Item region of the panel (you may need to enable the display of this column).

Viewing the notes associated with revisions of a component.

General Item Commands

Along with the view options, the Explorer panel's options area also includes the Add <item> command button, which applies to the currently selected type of folder.

This command invokes the creation of a new Workspace item of the selected type. When a component folder type is selected in the panel, for example, an button is offered. This will open a newly created component of that type in the Component Editor. Similarly, a button is shown when an Output Job type folder has been selected, and so on. The button will follow a component search, as entered in the component path field at the top of the panel, which creates a Part Request activity that applies to the component selected in the search results.

Drag & Drop Placement

Placement of certain Workspace Items into a PCB design project in Altium Designer is streamlined with the ability to drag & drop revisions of these Item types onto the active (and applicable) document, directly from the Explorer panel. Support is available to drag:

• A revision of a Component Item onto the active schematic document (or PCB document). The applicable model for the chosen domain will appear floating on the cursor accordingly.
• A revision of a Managed Schematic Sheet Item onto the active schematic document. A sheet symbol that references the sheet will float attached to the cursor.
• A revision of a 3D Model Item onto a PCB or PCB Library document, creating a 3D Body object that references that Item Revision.

Browse your Workspace for the required Item to be placed. Placement involves a specific revision of that Item, so be sure to expand the main Item entry to list all of its available revisions (click the button at the top-right of the panel and disable the Show only latest option to see all previous revisions). Then click on the required revision and drag an instance of it onto the design document.

In addition, Altium Designer supports access to, and placement of components from, the Components panel.

Downloading Content Data

Download the data stored in a revision of an Item by right-clicking on that revision and choosing the Operations » Download command from the context menu. The associated data will be downloaded into a sub-folder under the chosen directory, named using the Item Revision ID. The files can be found in the Released folder therein.

Binary File Content Type

Altium Designer, in conjunction with your connected Workspace, caters for the ability to store free files in a special content type – the Binary File Item. Such Items can be created to accommodate one or more files of any format. This allows you to effectively take advantage of the Workspace's secure nature, and underlines the Workspace as being the perfect place to store anything, including your source binary files together in a single entity. And facilitating the streamlined flow of data files, bi-directional drag-and-drop functionality is provided, enabling you to quickly move files between folders in your Workspace and folders in your Windows Explorer.

• Create an Item of the Binary File content type in the Workspace. A new revision of a Binary File Item can be created by uploading the applicable file(s). This can be performed in a couple of ways - see  Uploading Data into a New Revision of an Item for more information.
• If you need to change the file(s) stored in a Binary File Item, upload the required new file(s) to that Item – the new file(s) will be stored in the next revision of that Item.
• To open a file that is stored in a revision of a Binary File Item, select that file – on the Details aspect view tab for the revision – then right-click and choose the Open command from the context menu. The relevant application (or Altium Designer itself) will be used to present the file, where applicable to do so.

Using a Binary File with Template Preferences

As part of your Altium Designer Preferences, you are able to define default template documents used when creating a new document of a particular type. This is performed from the Defaults tab of the Data Management – Templates page of the Preferences dialog. A default template document can be file-based or from a connected Workspace.

For some document types (ActiveBOM Document, Out Job File, Multi-board Schematic, and Multi-board Assembly), a Workspace-based default template document can be sourced only from a binary file. So you need to upload the required template document into the revision of a binary file, and then use that for the new document default.

Upload a needed document (for example, an OutputJob file) to the initial revision of a new binary file.

Now when you try to define a new document default from the connected Workspace, you can browse for the binary file, and the preferences entry will populate accordingly.

Successful use of an OuputJob as a new document default, through the binary file that contains it.