Creating Projects and Documents

Now reading version 23. For the latest, read: Creating Projects and Documents for version 24

Parent page: Getting Familiar with the Altium Design Environment

A new PCB, Multi-board, or Harness design project can be directly or, for a Workspace project, by making an existing local project available in the Workspace or by cloning an existing Workspace project. The sections below describe how a new project can be created and design documents can be added to a project.

Creating a New Project Using the Create Project Dialog

A new project can be created from within Altium Designer using the Create Project dialog (File » New » Project).

As well as creating a new project in your connected Workspace, the Create Project dialog also supports creating and adding a new project to an existing external version control repository (with a working copy in your preferred location), or creating a new project in a specified folder on your local hard drive.

Setting up the Create Project dialog to create a new design project from within Altium Designer. Note that the Advanced options will be appropriate by default.
Setting up the Create Project dialog to create a new design project from within Altium Designer. Note that the Advanced options will be appropriate by default.

  1. In the Locations list, select the entry for your Workspace (it will appear with the name defined for it) – you must be actively connected to the Workspace to see this option in the listing. This will be the target server in which to store your new Workspace project.

    In a nutshell, project management is focused on securely storing and tracking changes throughout the design process, and ultimately, channeling the resulting design through to the creation of a physical item – such as an assembled PCB to be used in the final product. To meet these needs, Altium Designer provides a range of project management approaches that offer increasing levels of sophistication and capabilities, yet simplify the process from a designer's perspective. These range from local file-based storage and management, to local/remote Version Control System (VCS) storage approaches, and through to its advanced and recommended form where the management of design data is centered on the capabilities of a Workspace.

    A connected Workspace and its internal VCS service hosts and manages Altium Designer projects, and also provides simplified VCS operations, inherent design collaboration capabilities, advanced design data sharing, history tracking, Lifecycle management, and much more. Projects that are integrated with a Workspace are accessed directly from Altium Designer, such as from the Projects panel, or from the Workspace itself through its browser-based interface.

    Thanks to the intelligence built into the services provided by a Workspace, tasks such as VCS operations are simplified and automated, and additional design collaboration features such as user access control (sharing), commenting and history are available directly from within Altium Designer. The end result is a robust and secure project storage format and location that can become the central point for collaborative project design.

    When connected to a Workspace with one or more active process definitions for the Project Creations process theme, the ability to create a new project through the Create Project dialog is restricted to Local and VCS type projects only. Instead, the creation of Workspace-based projects comes under the control of active process definitions. Learn more about Process-based Project Creation.
  2. In the Project Type list, choose the type of project you wish to create, and choose from the applicable templates available as required. The <Empty> entry will create a shell project with no initial source documents.

    If you do not connect to your Workspace, you can still work with Altium Designer (under your valid Altium Designer license), but you will not be able to access that Workspace or any other services it provides. You will, therefore, not be able to use any Workspace project templates. You will only be able to use file-based templates defined locally and available from the templates folder specified on the Data Management – Templates page of the Preferences dialog (if the Template visibility option is set to Server & Local on this page).
    Learn more about Creating a Project Template.
  3. Enter a Project Name and optionally, a project Description.

    The project name should start with, and can contain A-Z, a-z, or 0-9. Underscores, dashes, and spaces are allowed, but the latter can only be used within the middle of the name (leading and trailing spaces will be ignored). You can not use the following words: AUX, COM1-COM9, LPT1-LPT9, CON, NUL, and PRN. In addition, the name cannot contain the following characters: \ . / ? % * : | " < >.

The Create Project dialog includes further options:

  • Check the Version Control option (the default) to impose all VCS capabilities on the project, such as history and advanced sharing capabilities. When unchecked, the project is stored in the Workspace and synchronized with the local copy – a 'mirrored' project in the Simple Sync format.

    The Version Control option is available only when connected to an Altium 365 Workspace. When connected to an Enterprise Server Workspace, this option is effectively checked.
  • When connected to an Enterprise Server Workspace, the Repository drop-down menu (if present) will list all design repositories managed through Workspace's Version Control Service, and which have been shared with you to use. Choose the repository in which to store the new project and its files – there is a single Git-based repository (Versioned Storage) available by default. If an SVN type repository is selected, an additional Repository Folder option is available for specifying or browsing to an alternative target folder within the repository itself.
  • Click the Advanced control to specify folder paths.
    • Use the Folder field to specify where the folder for the project – within the Workspace's folder structure – is to be created. The default path for new projects is specified on the Admin – Settings – Projects page of the Workspace's browser interface (by default, this will be Projects\<ProjectName>). Click the button to browse to and select a different Workspace folder, if required.
    • Use the Local Storage field to specify where the local version of the project will be stored on your hard drive. The default location is defined on the System – Default Locations page of the Preferences dialog. Click the button to browse to and select a different folder location, if required. This is the 'working' folder for the project and the local Git repository it is committed to. The project is ultimately, or at the time of committal, pushed to the centralized design repository in the Workspace (Versioned Storage), which is the remote Git repository.
  • Use the Parameters list area to add or remove custom Name/Value parameter pairs that are associated with the project and saved in the Workspace. Use the button to add a new parameter Name-Value pairing to the list. The Name and Value fields allow a maximum of 255 characters. These Workspace project parameters are saved in the Workspace with the new project and can be edited within the Workspace. By contrast, Project type parameters are saved in the project file (*.PrjPcb), and can be edited in Altium Designer. Both parameter types may be used as Special Strings in Altium Designer – access from the Properties panel with a placed Text String selected in the design space. Parameters defined for the project can also be viewed on the Parameters tab of the Project Options dialog (Project » Project Options).

With the project defined as required, click the button. The new project structure will be created in the specified local and Workspace folders. The project will be opened in the Projects panel, which will reflect the fully synchronized state that exists between the files in the remote design repository (in the Workspace) and the local (working copy) repository – as indicated by the associated icons. If created with the Version Control option unchecked (available in an Altium 365 Workspace only), the mirrored project will be shown in the Projects panel with an associated icon.

The newly created project committed to the Versioned Storage design repository in the Workspace.The newly created project committed to the Versioned Storage design repository in the Workspace.

Alternatively, if the new project has not been assigned a template with constituent documents, the project file (*.PrjPcb) and therefore, the structure of the project only will be created. The project is then opened in the Projects panel, which will show it as being Scheduled for addition, denoted by the associated icon. At this point you can add documents to the project, or simply save the structure to the Workspace in its current shell state. To do so, click the Save to Server control associated with the project entry in the Projects panel – also available from the right-click context menu, and from the main File menu. In the following Save to Server dialog, select/deselect files for inclusion, add an optional Comment, and then confirm the save process with the button. Once the project is added to the server, the Projects panel will reflect the fully synchronized state that exists between the files in the server repository and the local working copy, as indicated by the icons.

  • The project will appear in the Projects panel under an entry for the target Workspace, reflecting the name of that Workspace.
  • In addition, an entry for the project will appear on the Projects page of the Workspace's browser interface.
  • The project will initially be shared for Read/Write access with the designer who created it (Owner), and all Administrators for the Workspace.

    ► See Sharing a Design for more information on configuring project access permissions.

  • A new project also can be created directly in a Workspace through its browser interface on the designs page (select Projects), and subsequently opened for editing and addition in Altium Designer.
  • Along with the project file (*.PrjPcb), the project structure file (*.PrjPCBStructure) is created. This file contains information about the project hierarchy whether it is flat or hierarchical. This file is regenerated upon the dynamic compilation of the project (when a project document opens).
  • The Create Project dialog can also be accessed by right-clicking on the Workspace entry within the Projects panel and choosing the Create Project command from the menu.

Cloning a Project

To clone a Workspace project from within Altium Designer, right-click on the entry for the project in the Projects panel and choose the Clone command from the context menu. Use the Create Project Copy dialog to determine the Project Name (by default this will be the original project name with the suffix ' - Copy'), Description (which is not pre-populated), the Folder path (within the Workspace), and the Local Storage path (to the working copy).

No special permissions are required to clone a project. The cloned project is an exact copy of the original Workspace project and has the same editing properties with no restrictions, i.e. you cannot create a 'read-only' project. Also note that the copied project will be made in the same design repository as the original – you cannot change this as part of the copying process.
The Workspace Folder will, by default, be the same folder in which the original project is stored. Click to open the Choose Folder dialog (a trimmed-down version of the Explorer panel) to change folder as required. The Local Storage will, by default, be set to use the location defined on the System - Default Locations page of the Preferences dialog. Click to open a standard Windows dialog with which to change this location as required.

Clone a Workspace project from within Altium Designer.
Clone a Workspace project from within Altium Designer.

Each time you clone the project, a Project Cloned event tile will be added to the timeline of the cloned project's history. Also, the Project Created tile of the project copy will include a link to the original project. Learn more about Project History.
You can clone an existing Workspace project from the Open Project dialog. Select the project within your connected Workspace, then click on the Open Project As Copy control at the bottom of the right-hand Information pane. In addition, when browsing the project through Altium Designer's Explorer panel – configured in its default Project View rather than Classic View – the project can be cloned by clicking the button at the top-right of the panel.
You can only clone a Workspace project that has been opened from the currently connected Altium Workspace. If Altium Designer is not currently connected to the project's Workspace, or the project is not a Workspace project, the Clone command will not be available in the right-click menu.

Adding and Removing a Design Document

Once a project is established design documents can be added, edited or removed from the active project. The simplest way to add new design documents to a project is to right-click on the project name in the Projects panel and select Add New to Project from the context menu options. Alternatively, choose the required document type from the Project » Add New to Project sub-menu of the main menus to add a new document to the active project.

  • If the chosen document type can have defaults specified on the Data Management - Templates of the Preferences dialog, the chosen document type will be created using that default as a template.
  • The document is initially unsaved.

Add a specific or another type of document to a project.
Add a specific or another type of document to a project.

Other types of project-relevant documents can also be added to a project, such as text files, PDFs, spreadsheets, etc. To do so, use the Add Existing to Project option (or the Project » Add Existing to Project command from the main menu of the active document's editor) and set the File Type drop-down list in the Choose Document to Add browser dialog to All Files (*.*) so all file types can be accessed.

Design projects are not limited to only containing files that have been created by Altium Designer - just about any document can be included in a project. When the document is accessed from within Altium Designer, the system will attempt to determine the corresponding authoring/viewing tool based on the file's extension and settings in the Windows registry. Assuming a match can be found, Altium Designer will then launch the associated editor, either within its own editing environment or as a separate application. This means that you can include all manner of test, documentation, background, and specification documents with your design projects, and have the confidence that wherever the design project goes, all the supporting documentation will travel with it.
When adding existing documents to an Altium 365 Workspace project, note that there is a limitation for zip, 7z and rar files larger than 256 MB. Projects containing such files cannot be saved to the Workspace – you will receive a Git Error. Refer to the How to fix project data after Git Error with status code 471 Knowledge Base article to learn how to fix this issue.

To remove a document from the project structure, right-click on its name in the Projects panel and select the Remove from Project menu option or choose the Project » Exclude from Project command from the main menus. You will be prompted to choose:

  • Delete File – to permanently remove the source document file itself.
  • Exclude from Project – to remove the project's link to that document (and not delete the source document file itself). If it is currently open in the design editor window, it will be removed from its parent project but remain open in the panel as a free document. If, however, it is not currently open in the design space, removal will effectively close it.

You can also remove all documents within the focused category (sub-folder) from their parent project by right-clicking on the entry for the required category and choosing the Remove All command, from the context menu.

Removing a Project

For local projects, removing a project is a case of deleting files from your hard drive. Open the project folder in Windows Explorer and delete its content.

To quickly open an instance of Windows Explorer at the location where the project is stored, right-click the project's entry in the Projects panel and select the Explore command.

For Workspace projects (and other Workspace content such as components and released data), flexible functionality is available for removing directly from within Altium Designer, from the Explorer panel. Operating as a 'soft delete', the removal process provides increased options and information as you proceed, including relevant links to source items for review purposes. In the Workspace, deleted content is moved to a dedicated Trash location, where it can be retrieved or completely removed from the Trash page of the Workspace's browser interface.

For a Project, only the owner or an administrator can permanently delete or restore from the Trash.

To soft-delete a Workspace project, navigate to the project folder in the Explorer panel, right-click its entry and select the Delete Folder command from the context menu. Confirm the deletion in the Confirm Delete dialog that appears. If the project contains released data, another confirmation dialog will open, notifying you about the fact that this data will be deleted as well. Click Delete to proceed.

To quickly open the Explorer panel with the project folder selected, right-click the project's entry in the Projects panel and select the Show in Explorer command.

Soft delete in action. Here, a project is being deleted, along with its related release (if manufacturing packages had been created from any releases, those would also be deleted).
Soft delete in action. Here, a project is being deleted, along with its related release (if manufacturing packages had been created from any releases, those would also be deleted).

If you find an issue, select the text/image and pressCtrl + Enterto send us your feedback.

The features available depend on your Altium product access level. Compare features included in the various levels of Altium Designer Software Subscription and functionality delivered through applications provided by the Altium 365 platform.

If you don’t see a discussed feature in your software, contact Altium Sales to find out more.