Releasing an Output Job File to an Altium Vault

Old Content - see latest equivalent

Parent article: Configuration Data Items

Altium's Design Data Management System caters for the ability to formally release an output job configuration file (*.OutJob) into a target Item (and revision thereof) in a target Altium Vault. Once the OutJob file has been released, and its lifecycle state set to a level that the organization views as ready for use at the design level, it can be reused in future board-level design projects.

In addition, a released OutJob can be used as a configuration data item in one or more defined Environment Configurations. An environment configuration is used to constrain a designer's Altium Designer working environment to only use company-ratified design elements. Environment configurations are defined and stored within the Team Configuration Center - a service provided through an appropriately licensed Altium Vault installation, and the facilitator of this concept of Environment Configuration Management.

The following sections look at the process of releasing an OutJob into a target Altium Vault, so that it can be reused in future designs.

Creating the OutJob File

A defined OutJob file on the design side is mapped to an Output Job Item in an Altium Vault. Each release of the OutJob file stores the data into a new revision of that Item.

Simply use Altium Designer's OutputJob Editor to define the OutJob as required.

Example OutJob file defined ready for release to an Altium Vault.

You can now proceed to release the OutJob file. To do so requires the following steps:

  1. Link the OutJob file to the required revision of a target Item in a target Altium Vault. The Item must be of type altium-output-job, and the revision in which to release the OutJob data must be in the Planned state.
  2. Release the OutJob file into that targeted Item-Revision.

Maximizing Reusability – Making Your OutJob File Generic

A number of innovative features are available when configuring your outputs to make the resulting OutJob file as generic as possible. By keeping an OutJob generic, you can effectively maximize its ability to be reused across future design projects.

Generic Data Source Names

Many output generators use a specifically-named underlying document as their source, from which the applicable output data is generated – for example Gerber files generated from the PCB document FluxTriangulator.PcbDoc. However, doing so locks the OutJob file to being useful only with that document's parent design project. To keep things non-specific, a generic entry for the underlying Data Source is available for selection across many of the output generators. The following table summarizes which output generators are supported, and the generic entry (entries) available.

Category Output Generator Generic Data Source Entry
Netlist Outputs All [Project]
Documentation Outputs Composite, PCB 3D Print, PCB 3D Video, PCB Prints [PCB Document]
  Schematic Prints

[Project Physical Documents]

Assembly Outputs All [PCB Document]
Fabrication Outputs All [PCB Document]
Report Outputs Bill of Materials [Project]
[LiveBOM Document]
  Component Cross Reference, Report Project Hierarchy, Simple BOM, Report Single Pin Nets [Project]
Validation Outputs Environment Configuration Compliance Check, Electrical Rules Check [Project]
  Design Rules Check, Differences Report, Footprint Comparison Report [PCB Document]
Export Outputs AutoCAD dwg/dxf PCB, Export IDF, Export STEP [PCB Document]
  AutoCAD dwg/dxf Schematic [Project]

Layer Classes

You have the ability to add named layer classes to configurations for the following output generators:

  • PCB Prints
  • Gerber Files
  • ODB++ Files

This makes these output generators generically reusable. For example, add a class 'signal layers' and refer to it in the OutJob - any design that has a 'signal layers' class will be able to use that output generator without modification.

In the PCB print dialog, a few new concepts:

  • Layer class: to be inserted in a printout - every layer in this class will be printed in this print out.
  • Printout set: displayed as one printout in the dialog, it will generate a set of print outs, each containing one layer of a given iterated layer class, and any other additional layer or layer class.
  • Drill Printout set: displayed as one printout in the dialog, it will generate a set of print outs, each containing the drill guide or drill drawing layer, iterated over the layer pairs, and any other additional layer or layer class.

By adding a Drill Printout set for Drill guide layer which also contains the Layer class 'Mechanical layers' you could generate for any design drill guide prints with mechanical layers.

All accessed from the right-click menu.

Linking the OutJob to a Vault

Before any OutJob data can be added to a vault, there must be an Item defined in the vault to 'hold' that data. The Item is created before releasing the OutJob into the vault. The link to the target vault and Item Revision therein, is stored as part of the OutJob file.

The first step is to link the OutJob to the vault, using the File » Link Document to Vault command. The Link Document to Vault Item dialog will appear.

Controls for linking the OutJob file to an Output Job Item in a target vault.

Clicking the Choose button to the right of the Item Revision field will give access to the Choose Item dialog – essentially a trimmed incarnation of the Vaults panel. The field at the top-left of the dialog indicates which vault you are currently exploring. To select a different vault, click the  icon to the left of the vault name (or on the vault name itself) to access a menu of top-level vault management controls. This menu displays all vaults that you currently have an active connection to.

If you have not connected to a vault, use the Vault Administration command on the menu to access the Data Management – Vaults page of the Preferences dialog (DXP » Preferences), from where you can make a connection to the required vault as necessary.

With the required target vault active, you can either drill down through its folder hierarchy to select the required existing Item, or create the folder and/or Item as required, on-the-fly. Ensure that the Item-Revision chosen – which will receive the released OutJob data – is in the Planned state.

When creating the target Item, ensure that its Content Type is set to altium-outputjob.

Manually linking the source OutJob file to a planned revision of an Output Job Item, in the target vault.

Folder Type

Whether you have created an Output Job Item in the target vault beforehand, or are creating it in situ at the time of document linking, you will need to first create the folder in which that Item will reside. As part of folder creation, the folder's type can be specified. This has no bearing on the content of the folder – releasing OutJob files will always result in Output Job 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 Output Job Items, set its Folder Type as altium-outputjob-catalog.

Specifying the folder type - its intended use - provides visual indication of the content contained within that folder while 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. This can be a great time-saver when manually creating Output Job Items prior to release.

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. OUTJOB-001-{C000}).

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

The Item 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.

Item Lifecycle Definition and Revision Naming

When defining the Output Job Item, to which the source OutJob file is linked, be sure to specify the type of lifecycle management to be used for the Item, and the naming scheme employed for its revisions, respectively.

Once the OutJob file has been released into the initial revision of the Item, these schemes cannot be changed for that particular Item.

Specify the required schemes in the Item Properties dialog, using the Lifecycle Definition and Revision Naming Scheme fields respectively.

Selecting the Lifecycle Definition and Revision Naming schemes for a manually created Item.

Observing standard revision naming schemes and lifecycle definitions, across the various types of design item in a vault ensures smooth, consistent management of those items.

It is a good idea to add a comment and description as part of the Item's definition. This information is used when searching the vault and enables quick identification of what an OutJob offers.

Verifying the Link is Established

Once the required revision of the Output Job Item in the target vault is chosen, clicking OK in the Choose Item dialog will create the link between source OutJob file and target Item. Evidence of the link can be seen back in the Link Document to Vault Item dialog. Click OK and save the OutJob file – so that the link information is saved.

Evidence that the source OutJob file is now linked to an Item in the vault.

Performing the Release

With the link to the target vault and Item-Revision in place, the process of releasing the source OutJob file into the vault can proceed. Select the File » Release Document To Vault command. When the data has been prepared to be added to the vault, the Release confirmation dialog will appear. This dialog also includes a field to add any pertinent release notes. Click Yes to commit the OutJob to the vault.

After its release, the Revision State is updated in the Link Document to Vault Item dialog, which will now show Released (when using basic lifecycle management), or New From Design (when using another default management scheme). Click the Show in Explorer button to browse the released OutJob directly in the vault using the Vaults panel.

Browsing the released Output Job Item in the vault, using the Vaults panel.

The released data stored in the vault consists of the configuration data defined in the .OutJob file.

With the OutJob released, it can now be reused in new design projects. For more information on both its manual reuse, and reuse as part of a defined environment configuration, see Reusing a Managed Output Job Item.

The released data can be downloaded by right-clicking on the entry for the Item-Revision and choosing the Operations » Download command from the context menu. The downloaded folder for the Item-Revision will contain a Released sub-folder. It is in here that you will find the data – the OutJob file.

Re-releasing the Source OutJob

Re-releasing the OutJob file – to take into account any modifications – is a straightforward process:

  1. Make the changes to the OutJob's configuration as required.
  2. Create a new Planned revision for the target Output Job Item. This can be done from the Lifecycle view for the Item, in the Vaults panel, or from the detailed view for the Item. With the OutJob document active in the workspace, the latter can be accessed from the Link Document to Vault Item dialog by clicking the Details button (to the far right of the Item Revision field).
  3. Use the File » Link Document To Vault command to access the Link Document to Vault Item dialog and choose this new Item Revision.
  4. Use the File » Release Document To Vault command.

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.

An Output Job Item can be edited in this way directly from the Vaults panel. Access to file-less editing is provided through the Edit command on the right-click menu.

Releasing Multiple OutJob Files

Releasing single OutJob files to a target vault can be a tedious task – especially since release of a single OutJob requires that file to be open and active in Altium Designer. This is also the case if changes have been made affecting an array of source OutJob files, that need to be re-released into a new revision of each target Output Job Item.

To facilitate the release of multiple OutJob files to a target vault simultaneously, Altium Designer provides a Release Manager (File » Release Manager). Use it to batch-release OutJob files in a nominated source folder location.

Setting up for release couldn't be simpler:

  • Set the Document Type to Outjob.
  • Point to a top-level folder containing the OutJob files you want to release. Files can be stored in sub-folders within this folder.
  • Choose the target vault.
  • Choose to create a top-level folder in the vault based on the nominated top-level Windows folder, or choose an existing vault folder. You can optionally create sub-folders in the nominated vault folder, for each Windows sub-folder. Additionally, you can opt to create a vault folder for each source OutJob file.
  • Use the Default Options for New Released Output Job Documents region of the Release Manager to control how required new Items are created as part of the release process – in terms of Lifecycle Definition, Item Naming and Item Revision Naming schemes, and starting index.
  • Hit the Analyze Folders button.

Analysis of source folders and target vault folders (and Items) based on your chosen options will be performed and the source OutJob files detected will be listed. For each entry, the target Item will be displayed, its current and/or next revision (as applicable) and the action that will be performed by the release process.

Enable the OutJobs that you want to release and then click the Prepare Items and Documents button to effectively commit the link information to the source OutJob files involved in the release. Once saved, proceed with the release by clicking the Release Items button.

Batch-release OutJob files using the Release Manager.

You are reporting an issue with the following selected text and/or image within the active document: