Management of Projects from within Altium Designer

Parent page: Managed Projects

This document takes a look at working with managed projects from within Altium Designer, including:

• Creating a project - either directly or by making an existing, unmanaged project available online.
• Sharing a project - changing the access permissions for a project so that users that need to see and work with it have the ability to do so.
• Opening a project - to be able to work on it.
• Cloning a project - to quickly get an identical copy without having to build the project from scratch, which is great if your next project is very similar.

Creating a New Managed Project

There are two ways in which a managed project can be created from within Altium Designer:

• Creation of a new project through the Create Project dialog.
• Making an existing, non-managed project (regular project, or a project currently under version control) available to the Workspace - essentially 'registering' the project with the Workspace and creating a 'mirror' of it.

The following sections take a closer look at these two avenues of creation.

Through the Create Project Dialog

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

Setting up the Create Project dialog to create a new managed 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 managed project.
2. In the Project Type list, choose the type of project you wish to create, and choosing from the applicable templates available as required. If you have project templates created and released into your Workspace, these will appear listed as the only available templates from which to choose.
3. Enter a Project Name and optionally, a project Description.

The Create Project dialog includes further options:

• Check the Enable Formal Version Control option (the default) to impose all VCS capabilities on the project, such as Revisions and advanced sharing capabilities. When unchecked, the project is simply stored in the Workspace for basic shared access. More information.
• 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 server folder, if required.
  • Use the Local Storage field to specify where the project will be stored on your hard drive, prior to its committal to the centralized design repository. 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. These managed 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 workspace. Parameters defined for the project can also be viewed on the Parameters and Server Parameters tabs 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 (server) folders. The project will be opened in the Projects panel, which will show the project and its constituent documents as being Scheduled for addition, denoted by blue cross icons ().

Right-click on the project in the Projects panel and choose the Commit Project command or the Version Control » Commit Whole Project command. You will be presented with the Commit to Version Control dialog. Select the files you wish to commit to the Workspace's Versioned Storage design repository and click the  button. Once added, the Projects panel 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.

Commit and push the newly created project to the Versioned Storage design repository in the Workspace.

In addition, an entry for the project will appear on the Projects page of the Workspace's browser interface.

Commit without Push

For those unfamiliar with Git repositories, or for those just wanting to get their local design changes into the Workspace, using the  button in the Commit to Version Control dialog is the cleanest and most streamlined approach.

However you also have the option to Commit to your local Git repository, ahead of pushing changes to the remote Git repository (Versioned Storage) in the Workspace. To do so, select the Commit command as above, and in the Commit to Version Control dialog choose the Commit option from the  button drop-down menu. The changes will be saved to the local Git repository for that project, and the state of the files - as reflected in the Projects panel - will become Ahead of server ().

Example of committing a new project to the local Git repository.

These locally saved changes can be sent to the remote Git repository in the Workspace at a later time by executing a Push command. This can be performed in a couple of ways:

• Right-click on the project entry in the Projects panel and choose the Commit Project command from the context menu, or choose the File » Commit Project command from the main menus. In the Commit to Version Control dialog, click the  button. This will just push those files ahead of the server, and commit and push those that are not.

• Right-click on the project entry in the Projects panel (or on a specific file) and choose the Version Control » Push(n) command from the context menu – where n reflects the number of local commits that have been made (ahead of the server).

Once pushed, the Projects panel will reflect the fully synchronized state () that exists between the files in the remote repository (in the Workspace) and the local (working copy) repository.

Make an Existing UnManaged Project Available Online

You can also make an unmanaged project (regular project, or a project currently under version control) available to the Workspace - essentially 'registering' the project with the Workspace and creating a 'mirror' of it. This allows you to enjoy the collaborative features available through the Altium 365 platform, while keeping your original project right where it is. To do this, open the existing unmanaged project as normal in Altium Designer, then right-click on its entry in the Projects panel and select Make Project Available Online from the context menu, giving access to the Make Available Online dialog.

Make an existing unmanaged project available to the Workspace, essentially 'registering' it with the Workspace and creating a 'mirror' of it.

Use the Make Available Online dialog to change the project Name and add a Description. By default, the name will be that of the original project.

Check the Enable Formal Version Control option to add the project under the Workspace's own built-in VCS (Git). This option is unchecked by default, where the project files will simply be stored in the Workspace for basic shared access.

Click the Advanced link to expose the Folder field. This field is used to specify where the folder for the mirrored 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 server folder, if required.

With the properties for the mirrored project defined as required in the Make Available Online dialog, click OK. Projects that have been made available online - in the Workspace - will be shown in the Altium Designer Projects panel as follows:

• For a project that is not under external version control and when made available online the Enable Formal Version Control was left unchecked, the project is shown with the  icon only. This indicates the project as being registered with the Workspace, that a mirrored project exists, and that the two are synchronized. Saved local files are automatically synchronized with their mirrored project counterparts in the Workspace.

If the project is removed from the Workspace, the local (unmanaged) project will appear in the panel with the  icon, to show that it is no longer available online (in the Workspace).

• For a project that is under external version control, the project is shown with the  icon to indicate the project as being registered with the Workspace, that a mirrored project exists, and that the two are synchronized. Associated  icons reflect the fully synchronized state that exists between the external design repository and the local working copy. Once local file changes are saved and committed to the external design repository, those changes are automatically synchronized with their mirrored project counterparts in the Workspace.

If the project is removed from the Workspace, the local (unmanaged) project will appear in the panel with the  icon, to show that it is no longer available online (in the Workspace).

• For a project that is not under external version control and when made available online the Enable Formal Version Control was checked, the project and files will be committed and pushed to the Workspace's Versioned Storage design repository, with the Projects panel reflecting the fully synchronized state that exists between that remote design repository and the local (working copy) repository, as indicated by the associated  icons. The project behaves like a true managed project - not just 'registered' in the Workspace, but actually committed and under the Workspace's version control. Changes made to the design must be committed back to the repository in the Workspace.

The mirrored project will subsequently be available from the Projects page of the Workspace's browser interface.

Limitations when using an Existing External Version Control Repository

As mentioned previously, your unmanaged designs may already be tracked under an existing, external version control system (Git, SVN, EPDM, etc...). You can continue using this setup as before, and simply make the designs available to the Workspace by registering them with that Workspace - using the Make Project Available Online feature.

In this mode, every time you make changes to a design and commit those changes to your external VCS repository, that design data will be mirrored to the Workspace in the background, and all needed processing will be performed as usual - preview, where used etc. There are some limitations to be aware of however:

• Creation of a new design project still has to follow the old flow, i.e. create it manually in the external VCS repository, then register to the Workspace (using the Make Project Available Online feature).
• If design changes are made but the commit is not performed through Altium Designer (so externally using other tools), then those changes will not appear for the mirrored project in the Workspace, until the next commit operation is performed through Altium Designer.
• Opening of the project by a second person will require access to that external VCS repository.
• Rights management will have to be setup/maintained in two placess - in Concord Pro and in the master source (the external Git/SVN/etc VCS repository).

Controlling Project Synchronization

Once an unmanaged project has been made available online, controls over its online availability and synchronization are provided through the General tab of the Project Options dialog.

Options and controls relating to having made the project available online are presented on the General tab of the Project Options dialog.

Use the options available in the General region of the tab to make changes to the name of the project and/or its description. These affect the mirrored project within the Workspace only - the name of the local project is not changed.

In the Online Availability and Synchronization region of the tab, the Enable Formal Version Control option reflects the current style of online availability - either simple synchronization (option disabled), or stored under external VCS, or the VCS within the Workspace's Versioned Storage Git design repository (option enabled). Use the option to change between these two as desired. Note that if the local unmanaged project is stored under an external VCS repository, this option will be permanently enabled and cannot be changed.

Should you wish to stop the synchronization between your local project, and the managed incarnation of it that was made available in the Workspace, click the  button. The Turn off project synchronization window will appear. Click on the Unlink option, then click OK back in the Project Options dialog. The local project will no longer be associated with the project in the Workspace, reflected in the Projects panel by the local project being presented under the active Project Group (*.DsnWrk), rather than as an entry under the active Workspace. The project in the Workspace remains untouched - it is not removed by this action.

You can sever the connection between your local project and the incarnation of it made available in the Workspace.

You can always make the unmanaged project available online again. The General tab of the Project Options dialog will present the  button, with which to access the Make Available Online dialog. Refer back to the section Make an Existing UnManaged Project Available Online for more information.

A local, unmanaged project can also be made available online - in the Workspace - from the General tab of the Project Options dialog.

Sharing a Managed Project

Once a project is managed (available in the Workspace), you'll want to determine which users can actually access that project. This is done by sharing the project, or rather, by configuring its access permissions. Remember that a managed project - newly created or made available in the Workspace - is shared, by default, with the following:

• The Owner of the project, which is usually the designer who created it (or made it available in the Workspace): with full (Read/Write) access permissions.
• The Administrators role: with full (Read/Write) access permissions.

Access for a project can be configured directly from within Altium Designer from the General tab of the Project Options dialog. Use the Sharing region of the tab to configure sharing as required. Use the Add menu to select the type of sharing you wish to apply - Add User, Add Role, Add Anyone. For a user/role, choose the desired entity in the subsequent Search for dialog.

Configure access to your managed project directly from within Altium Designer.

Opening a Managed Project in Altium Designer

To work on a managed project, you effectively check it out as a local working copy. This is performed directly from within Altium Designer using the File » Open Project command. The Open Project dialog will appear, from where you can choose which managed project to open from your Workspace (when connected to a Workspace, that Workspace will appear in the Locations region of the dialog, distinguished by the  icon, and appearing with the name given to the Workspace). Only those managed projects that have been shared with you (you have permission to access) will be listed.

Once opened, the project will appear under an entry for the Workspace, in the Projects panel.

Choose which managed project to open, from within Altium Designer, from those currently shared with you.

You have the option to open the project to the default checkout path, or use the  drop-down menu to specify a custom path. The default checkout path is taken from the Document Path field on the System - Default Locations page of the Preferences dialog.

When browsing the project through Altium Designer's Explorer panel - configured in its default Project View rather than Classic View - click the  button, at the top-right of the panel, to open the project in Altium Designer (adding it to the Projects panel).

Cloning a Managed Project

To clone a managed project from within Altium Designer, right-click on the entry for the project in the Projects panel and choose the Clone Project command from the context menu. Use the Clone Project dialog to determine the Project Name, Description (which is not pre-populated), the Folder path (within the Workspace), and the Local Storage path (to the working copy).

Clone a managed project from within Altium Designer.

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.