Parent page: Managed Board Design Release
Once a design is considered ready for flight into the wider world, it needs to be released - a process that can often be underestimated.
Altium Designer provides powerful, high-integrity board design release management, courtesy of its Project Releaser. With an intuitive user interface, you are able to generate all manufacturing data for your project simultaneously - fabrication data, assembly data, design source, etc. The releaser also provides the ability to generate the assembly data for multiple detected variants of your board design at the same time. You don't even have to worry if you haven't created Output Job files - it'll do that for you if you ask it to!
The Project Releaser caters for all types of PCB project - unmanaged/non-version-controlled, under external VCS control, or managed through an Altium Vault - by offering two modes of operation:
- Online Mode - releasing all generated data to revisions of Items in a target Altium Vault. You don't even have to remember to increment Item Revisions, it is all handled for you.
- Offline Mode - releasing all generated data into a folder-based structure, all wrapped up in a single Zip file.
With the Project Releaser, you'll be able to generate your manufacturing data with simplified ease, and with the highest integrity. And you'll also be able to survey the fruits of that generation before you commit to finalizing the release (viewing Gerbers/ODB++ data in the CAM Editor for example), ensuring that the data you have generated is exactly the data required to get your board manufactured on time, first time.
This document takes a look at the release process from the perspective of releasing to a target Altium Vault. If you are not using an Altium Vault or are signed out from your Vault, you will be using the
Project Releaser in its Offline Mode, which is covered
here.
Accessing the Project Releaser
The graphical interface to the Project Releaser is the Release view, which can be accessed by:
- Choosing the Project » Project Releaser command from the main menus (with a source document for the required project open as the active document).
- Right-clicking on the entry for the required project, in the Projects panel, and choosing the Project Releaser command from the context menu.
Accessing the Release view - the user interface to the Project Releaser.
Release Mode/Target
The Project Releaser attempts to detect which release mode to use (Online or Offline), and the target of the release, automatically. Where a choice can exist, typically where the project has been released to one Altium Vault, and you are currently connected and signed in to another, the system will provide the options available to you.
When releasing to an Altium Vault, the target vault is stored as an attribute in the PCB project file. So you can have a target vault stored with the project that can be different to the vault in which you are currently signed in.
If you have a regular project (not managed and not under VCS), and are only connected to the Altium Content Vault, then Offline mode of releasing will be entered automatically.
Detecting Output Job Files
If your project currently has no Output Job file(s) associated to it, the Project Releaser will detect this, and you will be asked if you wish to add default ones. If you opt to do so, the following will be created:
- Fabrication.OutJob - with the following outputs defined:
- Documentation Outputs: PCB Prints
- Fabrication Outputs: Gerber, NC Drill, and IPC-2581
- Validation Outputs: Design Rules Check, Footprint Comparison Report
- Export Outputs: Save As/Export PCB (in ASCII format)
- Assembly.OutJob - with the following outputs defined:
- Documentation Outputs: PCB 3D Print, Schematic Prints
- Assembly Outputs: Pick and Place Report, Assembly Drawings
- Report Outputs: Bill of Materials
- Export Outputs: Export STEP
These default Output Job files are sourced from the following default installation folder: \Users\Public\Documents\Altium\AD<Version>\OutputJobs.
You can run with the default files as they are, massage them to suit your needs, and even add additional Output Job files. Simply define the Outjobs as required within the default folder, or your own custom folder location. If using your own folder, specify that location using the
OutputJob Path field, on the
System - Default Locations page of the
Preferences dialog. All Output Job files found in the specified location will be added to the project.
If you have at least one OutJob file defined for the project, this auto creation will not be offered.
Detecting Variants
A very powerful aspect of the Project Releaser, is that it will detect defined variants for your design and create Assembly Data sets for each, ready for release. Each Assembly Data set will appear with (default) target item naming in the form:
PCBA-[ProjectName]-[VariantName]
The Data set for the base (non-varied) design will be PCBA-[ProjectName]-[No Variations].
The [VariantName] suffix ensures that the correct variant is being used when generating data from the assigned OutJob file(s).
Additional Assembly Data sets created based on detection of variants defined for the design.
Setting Vault Item Naming Schemes
When releasing a project to a target Altium Vault for the first time, you can define how the target data items in the vault (whose revisions receive the generated data) are named. This is done on the Item Naming tab of the Project Release Options dialog, which is accessed by pressing the Options button, at the bottom-left of the view (or by clicking on the Target Revision link for a data set to be released, and choosing Edit from the context menu). Use this tab to:
- Define the name for the project. By default, this will be filled with the actual name of the project.
- Define the top-level target folder (in the vault) in which the data will be released.
- Define default naming schemes for the various data items that can be generated as part of the release.
The Project item is not an item created to receive release data, but rather an entity used as the anchor point for presenting the overall project view of the released data items, and how they are all connected, when viewing a managed project in the
Vaults panel. For more information, see
Viewing a Released Managed Project.
To change any of the naming schemes, simply click the Settings button to access the Naming Template Settings dialog.
Set the target folder and define the naming for generated data items in the target Altium Vault.
From the Item Naming tab of the Project Release Options dialog, you can click on a naming scheme entry directly, and change the naming as desired. Alternatively, click the button at the right of the field to access the Choose Item dialog, which allows you to target an existing Item in the target vault.
Item naming templates can be changed at any time during the first stage of the Release view, when configuring the data that is to be released into the target Altium Vault. After data has been generated for a particular data set, and uploaded to the vault, the associated naming cannot be changed.
The Release Process
With target vault data Item naming defined as required, you can now get started with the release process. This is a staged flow, with the entries on the left-hand side of the Release view showing you at-a-glance, which stage you are currently at.
Stage 1 - Configure Vault Release
This stage of the release process is where you specify the type(s) of data that you wish to generate. Data Items that can be released are:
- Source Data - a snapshot of the source design.
- Fabrication Data - the data required by a Fabrication House to create the bare board.
- Assembly Data for the Base Design (no variations) - the data required by an Assembly House to fully populate the bare board in accordance with a Bill of Materials, and for the non-varied base design.
- Assembly Data for Design Variant n - the data required by an Assembly House to populate the bare board in accordance with a Bill of Materials, and for Variant n of the base design.
The number of assembly data sets will correspond to the base (non-varied) design, and all detected variants defined for that design.
In addition, you can add and configure Custom Data sections - allowing you to create a customized set of release data. This is more for backward compatibility, or custom data flows. No references are created, except to the source data. Any number of custom data sets can be added and configured as part of the release (click the Add Section button beneath the list of currently defined data items).
Stage 1 of the project release process - configuring what is to be included in the release (what data to generate).
The Source Data item is always included for a release. The other data items can be optionally included.
For the Fabrication and Assembly data items to be included in a release requires at least one OutputJob file be assigned to them. If you have Output Job files with names that start with the sub-strings 'fab' and 'ass', those OutJobs will be assigned automatically to the Fabrication Data and Assembly Data sections respectively, when the Release view is first accessed. If not, you will need to assign the applicable OutJobs in each case manually. This can be done from the Release Options tab of the Project Release Options dialog (click the Options button at the bottom-left of the view to access).
Assign OutJobs to the applicable data sets as required.
The
Release Options tab can also be used to change the release target. Set the entry to a different Altium Vault target, using the button at the far right to access the
Data Management - Vaults page of the
Preferences dialog, in which to define connections to vaults as required. Alternatively, choose the
Folder setting to switch to releasing locally, in Offline mode.
Click on the link next to a Target Revision entry, back in the main view, to access a menu of commands. Choose the Edit command to access the Item Naming tab of the Project Release Options dialog, from where you can change the name of the target Item (and initial revision) that will be created, or choose Browse to point to an existing target Item-Revision in which to release. The Auto entry - used by default - lets the system handle the revisions, so that you don't need to create planned revisions where they do not currently exist. In addition, you can also target a specific revision of a target item, using the Custom entry - read about how to enable this functionality in the Additional Settings collapsible section, below.
Additional Settings
There are additional settings that can be defined, relating to project release, on the Data Management - Vaults page of the Preferences dialog:
- The folder used to temporarily store generated files prior to uploading to the target Altium Vault can be set to the automated location (\Users\<ProfileName>\AppData\Local\Temp for a default installation), or manually overridden with a folder of your choice.
- Enable the Delete contents after exiting release mode option, to have the temporary storage folder effectively flushed after finishing the release process.
- The name of each generated output can be optionally prefixed with the Item ID and Revision ID (e.g.
[FAB-Bluetooth_Sentinel-A.1] Validation.PDF). Simply enable the Prepend revision HRID to file names option.
- Enabling the Allow manual initial revision Id option will add a Custom entry to the context menu associated to the link next to a Target Revision entry (in the initial Configure Vault Release stage of the release process). Use this command to access the Custom Revision ID dialog, from where you can manually specify the revision of the target item into which the generated data will be released.
Additional preferences relating to the project release process.
With the data items that are to be created as part of the release configured as required, click the Prepare button at the bottom-right of the page. Several pre-release checks are now performed, including:
- Making sure that the project and all files have been saved.
- Making sure that the project and all relevant file(s) are committed to VCS if applicable.
- Making sure that each enabled data item has been given a name.
- Ensuring that the user has rights to create the target item (and revision).
- Creating the required target Items (and planned revisions) in the target vault, where they do not currently exist, and ensuring the next revision is used for those items that do.
If any issues are found, you will be offered solutions with which to resolve them (such as saving locally modified files, and committing to VCS).
The Source Data Item is generated at this time - with a snapshot of the source design project files released to the target item revision.
Stage 2 - Validate Project
After Stage 1 completes without issue, this next stage of the release process is run automatically when one or more Validation-type reports are detected in assigned OutJob file(s). All defined validation output generators, defined in an Output Job file assigned to the data item being released, are run. This includes running any of:
- Differences Report – using the comparator to determine if the source and PCB design documents are correctly in-sync.
- Electrical Rules Check – checking the electrical/drafting validity of the captured source design.
- Design Rules Check – checking the validity of the PCB document in relation to specified board-level design constraints.
- Footprint Comparison Report – comparing footprints on the board against their source library to ensure they are up-to-date, and matched.
- Component State Checking - checking for components that are in restricted states. As part of configuration, you determine the action to be taken for each currently defined state, of each currently defined Lifecycle Definition in the target vault; no action, a warning, or generate an error. The latter will prevent release of the design. In addition, running the check will generate a handy HTML-based report, allowing you to see at-a-glance which design components are not in valid states.
- Environment Configuration Compliance Check – checking that only data items permitted through the environment configuration available for use by your assigned role (if applicable), are being used. This check can also ensure that all design items are sourced from an Altium Vault.
If validation is successful, the 
icon is presented, with the text Passed. If not, the 
icon will be displayed, with the text Failed.
The release will fail if any validation checks are not passed successfully.
Clicking Cancel at the bottom-right of the page will stop the release process.
Stage 3 - Generate Data
After Stage 2 completes without issue, this next stage of the release process is run automatically. This is where all other outputs - defined in the OutJob file(s) assigned to the included Data Items - are run, to generate the data to be released into the relevant target items in the vault.
As with the other stages, but more noticeable with this stage, since it takes longer to run, icons are used to present the progress of generation:
- not yet run/generated.
- being run/generated.
- generated successfully.
- generation failed.
Clicking Cancel at the bottom-right of the page will stop the release process.
Stage 4 - Review Data
With all validation checks passed, and output data generated, this stage of the release process allows you to review the generated data.
Review generated data, checking that all is as it should be, prior to committing to the release, and uploading the data to the target vault.
The page defaults to present a simple (Compact) view of the generated data. Switch to a more detailed view by clicking the Details control associated to a section of interest.
Click on a Details link to switch from simple to detailed view of the generated data for the associated section. Switch back again by clicking the Compact link.
Output Generation States in Detailed View
The following table lists the possible output states, when data is being generated and viewed from the detailed view:
|
State
|
Description
|
|
|
Output has not yet been generated/does not exist.
|
|
|
Output has been generated, but changes have since happened on the design side, making the validity of this data no longer current.
|
|
|
The output is currently in the process of being generated.
|
|
|
The output is validation-based and has generated a report free of any errors. For an ERC report, there are either no errors, or the level of those errors falls within the specified maximum tolerated error level for that report.
|
|
|
The output (excluding validation-based outputs) has generated successfully.
|
|
|
The output has not generated successfully. For a validation-based output (DRC, ERC, Differences, Footprint Comparison, Configuration Compliancy, Component Checking) this means errors exist within the source design documents that are causing certain check(s) to fail. For a standard output, the output could not be generated successfully. Perhaps Fatal Errors exist when performing a pre-generation compile, or something is amiss in the configuration of the associated output generator, in the Output Job file.
|
In the Compact view of the generated data, click a View link to open the associated data file, or file set, either within the relevant editor within Altium Designer (e.g. the CAM editor), or within the relevant external application (e.g. Microsoft Excel). In the Detailed view, simply double-click on an entry to view just that file.
In the Source data section, in Compact view, clicking the View link will open Windows File Explorer at the temporary folder in which the snapshot of the source files for the project have been saved.
In the Detailed view, commands on the right-click context menu provide the ability to open a document, and explore to where it has been generated. You can also add data columns for folder location and creation date - simply right-click on the heading area for a grid and choose the Select Columns command, giving access to a dialog with which to tailor the data presented.
If, after reviewing the data, you find you need to make modifications, simply click the Cancel button at the bottom-right of the page. A confirmation dialog will appear, alerting you to the fact that all generated data will be lost - clicking OK will cancel the release and you will be returned to Stage 1 of the process.
The system naturally prevents any modification of design files between preparing the release and releasing the data to the target vault. If you do change design files in any way, the release process will terminate, and you will return to the initial stage, prior to release preparation.
If the generated data all looks good, proceed with the release by clicking the Release button (also at the bottom-right of the page). The Confirm Release dialog will appear, summarizing the configurations of the project that will be released to the target Altium Vault. You also have the opportunity here to add any pertinent release notes.
Confirmation of what will be released, in terms of the Item-Revisions generated,
and the ability to add release notes.
Stage 5 - Upload Data
After confirming the release in the previous stage, this next stage is automatically entered. It simply presents progress of data upload into the revisions of the relevant data Items in the target Altium Vault.
This stage simply reflects progress of the upload of generated data to the linked Item-Revisions in the target Altium Vault.
Stage 6 - Execution Report
This is the final stage of the process, providing a summary of the release.
The final report for the release.
Use the Navigation Links to quickly access the associated Item Revision, containing the released data (Fabrication Data, Assembly Data, and any Custom Data sets), in the Vaults panel - your portal to any connected vault.
Viewing the released data for the project, directly in the target Altium Vault, courtesy of the Vaults panel.
Viewing a Released Managed Project
If your design project is a Managed Project, then you have one extra piece of functionality available to you after the release is complete. By clicking on the Project Page link, the last of the Navigation Links at the top of the Execution Report page, you will open the Vaults panel, presenting the project in the Project View - only available for Managed Projects.
For a managed project, you can explore the project in the Vaults panel in more detail, courtesy of the Project View.
This view is the same as the Projects page, available through the vault's browser-based interface. The following tabs are available within the view:
- Stream - detailing recent activity for the project.
- Releases - what has been released, presented in terms of the assembled packages (including assembly data, fabrication data for the linked/parent bare board, and source files from which both have been generated).
- Working Files - the source design files.
- Structure - a graphical representation of how the generated data links together, all under the umbrella of the parent design project.
That's it - with your project released, you can simply close the Release view (using the Close button at the bottom-right of the view). And when you need to re-release the same project in the future, the Project Releaser facilitates this quickly and easily, and increments the target Item-Revisions automatically.
Offline Release Mode
As well as the Online release mode described previously, the Project Releaser also caters for local, Offline release. Typically, this mode of releasing would be used if you don't use an Altium Vault, or if you cannot be currently connected to your Altium Vault. And while the Project Releaser will automatically determine the mode where possible, or offer options where that is not so clear cut, you can always force the use of Offline mode. The latter is performed by setting the Release Target to Folder, on the Release Options tab of the Project Release Options dialog (click the Options button, while at Stage 1 of the release process).
You can quickly tell if the Project Releaser is configured in its Offline mode, by:
- The title of stage 1 reading Configure Local Release, instead of Configure Vault Release (when in Online mode).
- The title of Stage 5 reading Pack Data, instead of Upload Data (when in Online mode).
The Project Releaser configured in local, Offline mode.
The release process is very similar to that described for the Online release mode, just targeting release of data to local folders instead. Rather than repeating the information described earlier, here we'll just outline the stages involved, and highlight any differences.
Stage 1 - Configure Local Release
Here is where you configure the data that you want to be generated from your design project. Source data is always included as part of a release, with the option to include fabrication, assembly (base and/or variations), and any custom data, as required.
For each data set to be generated, you need to specify a target folder where that data will be stored. Default folder names are used as follows:
- Source Data - will be generated in the Sources folder.
- Fabrication Data - will be generated in the Fabrication folder.
- Assembly Data for no variant - will be generated in the Assembly folder.
- Assembly Data for <VariantName> - will be generated in the Assembly <VariantName> folder.
- Custom Data <Custom - n> - will be generated in the <Custom - n> folder.
You can of course change this default naming to suit your requirements. To do so, simply click on a current folder name and choose Custom from the subsequent context menu. Then enter the desired new name for the folder and press Enter.
With the data sets to be created as part of the release configured as required, click the Prepare button at the bottom-right of the page. Several pre-release checks are now performed, including:
- Making sure that the project and all files have been saved.
- Making sure that the project and all relevant file(s) are committed to VCS if applicable.
- Making sure that each enabled data item has been given a target folder.
If any issues are found, you will be offered solutions with which to resolve them (such as saving locally modified files, and committing to VCS).
The Source Data is generated at this stage - with a snapshot of the source design project files released to the target folder.
Stage 2 - Validate Project
After Stage 1 completes without issue, this next stage of the release process is run automatically when one or more Validation-type reports are detected in assigned OutJob file(s). All defined validation output generators, defined in an Output Job file assigned to the data item being released, are run. This stage runs the same as it does when releasing in Online mode.
The release will fail if any validation checks are not passed successfully.
Clicking Cancel at the bottom-right of the page will stop the release process.
Stage 3 - Generate Data
After Stage 2 completes without issue, this next stage of the release process is run automatically. This is where all other outputs - defined in the OutJob file(s) assigned to the included Data Items - are run, to generate the data to be released into the relevant target folders. This stage runs the same as it does when releasing in Online mode.
Clicking Cancel at the bottom-right of the page will stop the release process.
Stage 4 - Review Data
With all validation checks passed, and output data generated, this stage of the release process allows you to review the generated data. This stage behaves in much the same way as when releasing in Online mode.
Review generated data, checking that all is as it should be, prior to committing to the release, and packing the data into the localized zip file.
In the Compact view of the generated data, click a View link to open the associated data file, or file set, either within the relevant editor within Altium Designer (e.g. the CAM editor), or within the relevant external application (e.g. Microsoft Excel). In the Detailed view, simply double-click on an entry to view just that file.
If, after reviewing the data, you find you need to make modifications, simply click the Cancel button at the bottom-right of the page. A confirmation dialog will appear, alerting you to the fact that all generated data will be lost - clicking OK will cancel the release and you will be returned to Stage 1 of the process.
The system naturally prevents any modification of design files between preparing the release and releasing the data to the target folder(s). If you do change design files in any way, the release process will terminate, and you will return to the initial stage, prior to release preparation.
If the generated data all looks good, proceed with the release by clicking the Release button (also at the bottom-right of the page). The Confirm Release dialog will appear, showing the location and name of the zip file that the generated files will be packed into. By default, this will be located in the same folder as the PCB project itself, with the name <ProjectName> (<Date> <Time>).zip. Change this to suit your requirements.
Stage 5 - Pack Data
After confirming the release in the previous stage, this next stage is automatically entered. It simply presents progress of data being packed into the localized zip file.
This stage simply reflects progress of the packing of generated data into the target zip file.
Stage 6 - Execution Report
This is the final stage of the process, providing a summary of the release.
The final report for the release.
Use the Navigation Link provided to quickly explore (in Windows File Explorer) to the packed zip file.
Quickly browse to the packaged zip file of locally released data, directly from the Execution Report stage of the releaser.
