Parent page: Altium Vault
Altium Designer, in conjunction with the Altium Vault, brings support for Managed Projects. Managed Projects target the development stage of the project lifecycle, simplifying the creation and ongoing workflow for version controlled projects. Centralized storage under the control of the Altium Vault also enables this feature to be a foundation for other collaborative services.
Some key benefits to using Managed Projects are:
- Simplified storage. No need to make decisions about storage locations. Backup and other basic services are taken care of.
- Foundation for collaborative features.
- Enforced version control.
- Beneficiary of a dedicated commenting system.
- Notifications and status. Document status including local modifications is visible to entire design teams.
- Concurrent PCB design works without any complex setup.
Technically a Managed Project is the combination of meta information stored on the server, along with tight integration with the Vault's local SVN-based Version Control service. The typical work flow is as follows:
- A user creates a new managed project (via the New Project dialog in Altium Designer, from the Vault's browser-based interface, or by converting an existing project (in Altium Designer)). During creation, that user defines the project's name, description, and svn design repository.
- In the Vault's browser-based interface, or directly within Altium Designer, access to the project is defined and managed.
- All collaborators select the project for opening (either from within Altium Designer, or from the Vault's browser interface) after which it is automatically checked out.
The beauty of Managed Projects is that they are version controlled by default, and can be collaboratively worked upon without having to worry about shared drives, servers, agreements etc.
Prior to creating a new Managed Project, or converting an existing non-managed project, ensure that a Design Repository exists in which to store that project, and all future projects. Design Repositories are centrally managed as part of the Altium Vault. Such repositories can be created through the local Version Control service - part of your Altium Vault installation. Alternatively, you can connect to an external repository. Irrespective of how it is created, centralized management of your organization's design repositories ensures that all of your projects are stored exactly where they are supposed to be stored, and not in hap-hazard fashion across designer's hard drives!
Creating a New Managed Project
There are three ways in which a Managed Project can be created:
- Creation of a new project within Altium Designer.
- Creation of a new project within the Vault's browser-based interface.
- Conversion of an existing, non-managed project from within Altium Designer.
The following sections take a closer look at these three avenues of creation.
Through Altium Designer
From within Altium Designer, a new Managed Project can be created using the New Project dialog (File » New » Project):
- Select the project type, choosing from the applicable templates available as required.
- Give the project the desired name.
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: \ . / ? % * : | " < >.
- Use the Location field to determine where, on your local drive, to initially store the project, prior to its commital to the centralized Design Repository.
- Use the Project Kind field to choose the Managed option.
- The Repository field will list all Design Repositories managed through the Altium Vault's local 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.
- Use the Repository Folder field to specify the name of the folder within the repository in which to accommodate the project and its associated files. By default, this will take the project's name.
- Use the Vault Folder field to specify where the folder for the project - within the Vault's folder structure - is to be created. By default, this will be Projects\<ProjectName>.
The default path for new projects - within the Vault's folder structure - is specified on the
Settings - Projects page of the
Vault's browser interface. Access this page by choosing the
SETTINGS entry from the
ADMIN menu, then clicking on the
Projects entry, in the navigation tree on the left.
Setting up to create a new Managed Project from within Altium Designer, courtesy of the New Project dialog. Note that only those central Design Repositories
that are shared with you will be available for selection from the Repository field.
After clicking OK, the new project will be created locally, in accordance with the defined Location. The project will be opened in the Projects panel, which will show the project and files as being Scheduled for addition, denoted by a blue cross icon (
).
Right-click on the project in the Projects panel and choose the Version Control » Commit Whole Project command or Save Managed Project command. You will be presented with the Commit to Version Control dialog. Simply select the files you wish to commit to the Design Repository and click OK. Once added, the Projects panel will reflect the fully synchronized state that exists between the files in the repository and the local working copy.
Commit the newly created Managed Project to the target Design Repository.
In addition, an entry for the project will appear on the PROJECTS page of the Vault's browser-based interface.
The newly-created Managed Project, evident on the PROJECTS page of the Vault's browser interface.
The project will initially be shared for Read/Write access with the designer who created it, and all Administrators for the Altium Vault. In addition, it will be shared for Read-only access publically, meaning that all users of the Vault can view the project. For more information on configuring project access permissions, see
Sharing a Managed Project.
Through the Vault's Browser Interface
A Managed Project can be created directly through the Altium Vault's browser interface:
- Sign in to the interface and access the PROJECTS page. Any previously created projects will be listed here.
- Click the
button at the top-right of the page. The Add Project pop-up window will appear.
- The window will initially present in simplified view. Simply enter the desired name for the project, a description (if required), and, if available, choose from any Managed Altium Designer Project Templates that exist in the Vault.
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: \ . / ? % * : | " < >.
- To access more controls - putting the window in advanced view - click on the Show additional fields control. The following fields will present:
- Vault Folder - use this field to specify where the folder for the project - within the Vault's folder structure - is to be created. By default, this will be Projects\<ProjectName>. The default path for new projects - within the Vault's folder structure - is specified on the Settings - Projects page of the Vault's browser interface. Access this page by choosing the SETTINGS entry from the ADMIN menu, then clicking on the Projects entry, in the navigation tree on the left.
- Project Type - use this field to specify the type of project, from a list of all project types supported by Altium Designer.
- Repository - this field will list all Design Repositories managed through the Altium Vault's local 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.
- Repository Folder - use this field to specify the name of the folder within the repository in which to accommodate the project and its associated files. By default, this will take the project's name.
Defining a new Managed Project directly through the Vault's browser interface.
After defining the new project as required, click Save - the new project will be created, with an entry for it appearing back on the PROJECTS page of the interface.
Additional Managed Project, added to the list of centrally-managed projects.
The project will initially be shared for Read/Write access with the designer who created it, and all Administrators for the Altium Vault. In addition, it will be shared for Read-only access publically, meaning that all users of the Vault can view the project. For more information on configuring project access permissions, see
Sharing a Managed Project.
Conversion of an Existing Non-Managed Project
You can also create a Managed Project from an existing non-managed one, simply by converting the latter to the former. To do this, open the existing non-managed project as normal in Altium Designer, then right-click on its entry in the Projects panel, and use the Convert to Managed Project command from the context menu.
If the Convert to Managed Project option is not available from the menu, it means that the project is currently under Version Control (in a local or network VCS Design Repository), or has been so in the past.
This can be resolved by creating a 'clean' copy of the project (one not associated with VCS) in another local folder and converting that version to a Managed Project.
Steps for creating a Managed Project from a project managed by a conventional VCS
- Open the project in Altium Designer:
- For a project currently under Version Control, use File » Checkout to open (check out) the project from its VCS repository to a local working folder.
- For a project that is no longer under Version Control, use File » Open Project to locate and open the project from its local folder.
- Use the Project Packager (Project » Project Packager) to create a single zip file of the project, which by default, will be stored in the project's local source directory - typically, a path such as
C:\Users\Public\Documents\Altium\Projects\MyProject.
- In the operating system, create a local working folder specifically for Managed Projects, for example:
C:\Users\Public\Documents\Altium\ManagedProjects.
- Move the project's packaged zip file to the new folder (
...\ManagedProjects) and extract its contents: right-click - Extract All and rename to suit. The resulting path to the duplicated project folder would therefore be C:\Users\Public\Documents\Altium\ManagedProjects\MyProject.
- If the project was previously a Managed Project, open its Project file (
*.PrjPcb) in a text editor such as Windows Notepad and delete the ManagedProjectGUID= entry, which can be found under the first [Design] section. Save the edited Project file.
- Back in Altium Designer, navigate to and open (File » Open Project) the newly duplicated project from its folder – that is, from where the project was unzipped.
- Right click on the project file and select the Convert to Managed Project command, which should now be available.
The Convert to Managed Project command opens the Convert to Managed Project dialog, which operates in two modes - Simple and Advanced. Click the button at the bottom-left to switch between these two modes accordingly.
- Simple Mode - requires you to determine the project's name, and a description. By default, the name will be that of the original project.
- Advanced Mode - provides the ability to specify the target Design Repository, managed through the Altium Vault that you are currently signed into. Choose from all managed repositories shared with you, and that are defined through the Vault's Version Control service (on the VCS page (ADMIN » VCS) of the Vault's browser interface). The repository path and directory therein are shown, the latter of which can be modified as required (by default a folder of the same name as the project will be created within the repository). The path to the local working copy of the project is also reflected. You also have the ability to define a Vault Folder, in which data for the project will be released when using Altium Designer's Project Releaser. By default, this will be Projects\<ProjectName>.
Convert an existing project to a Managed Project.
The conversion process involves the following steps:
- With the properties for the Managed Project defined as required in the Convert to Managed Project dialog, click OK.
- The Add to Version Control dialog will subsequently open with all pertinent files selected for addition. Check all is as required and click OK.
- The project and files will be identified in the Projects panel as being Scheduled for addition, denoted by a blue cross icon ().
- Right-click on the project in the Projects panel and choose Version Control » Commit Whole Project. You will be presented with the Commit to Version Control dialog. Simply select the files you wish to commit to the Design Repository and click OK.
Once added, the Projects panel will reflect the fully synchronized state that exists between the files in the repository and the local working copy.
Adding and commiting the project to the target managed Design Repository, reulting in the project becoming a true Managed Project.
The newly-converted Managed Project will subsequently be available from the PROJECTS page of the Vault's browser interface.
The converted project is added to the list of centrally-managed projects.
The project will initially be shared for Read/Write access with the designer who converted it, and all Administrators for the Altium Vault. In addition, it will be shared for Read-only access publically, meaning that all users of the Vault can view the project. For more information on configuring project access permissions, see
Sharing a Managed Project.
Browsing Managed Projects
As mentioned already, Managed Projects are available to browse from the PROJECTS page of the Vault's browser interface.
The PROJECTS page of the Vault's browser interface - command central for managing your managed projects.
Each project is listed in terms of the following information:
- Name - the name of the project.
- Author - the user who created the project.
- Last modified - the date on which the project was last modified.
The list of managed projects is automatically sorted by Last modified date, with the most recently modified project appearing first in the list. The list can be sorted by any of these data columns - click once within a column header to sort in ascending order, click again to sort in descending order.
For each project, the following controls are provided (and detailed in the linked sections that follow):
Open - open the project, via its detailed view.
Edit - edit the project, in terms of its Name and/or Description.
Share - access controls with which to configure project access permissions.
Remove - remove the project.
Detailed Project View
Clicking the Open control () associated with a managed project - or clicking on its name - will give you access to the detailed Project view.
Accessing the detailed Project view for a managed project.
This view of a project can also be accessed within Altium Designer, through the
Vaults panel. The view is available once the project has been released to the Vault, and the aspect view for the Project Item has been switched to
Project View.
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, which can be downloaded in a single Zip file.
- Structure - a graphical representation of how the generated data links together, all under the umbrella of the parent design project. Click a link to access that Item-Revision within the Vault, on the VAULTS page of the browser interface.
A number of additional controls are also available for the presented project:
- VCS Location - click this link to open the parent design repository, in which the project resides, in your external SVN client browser.
-
- click this button to open the project within Altium Designer (by opening the dxp.exe file). If Altium Designer is already running, the project will be opened in that instance.
-
- click this button to access the Edit Project window. From here, you can change the project's Name and/or Description. All other fields are non-editable, providing information only.
-
- click this button to access the Manage Permissions window, with all the controls necessary to share the project with other users. See Sharing a Managed Project for more information.
-
- click this button to essentially follow the project. You will receive applicable notifications related to the project (e.g. updated, released, permission changes) on the project's Stream tab, as well as the main HOME and STREAM pages of the browser interface.
-
- click this button to essentially stop following the project. No further notifications relating to that particular project will be received on the project's Stream tab, nor the main HOME and STREAM pages of the browser interface.
-
- click this button to access the Clone Project window, providing the controls to make an identical copy of the project. See Cloning a Managed Project for more information.
-
- click this button to remove the project from the repository, rendering it no longer managed. If you have checked out the project locally, you will still have this local working copy.
Sharing a Managed Project
Once a project is managed, 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 converted - is shared, by default, with the following:
- The designer who created (converted) the project - full (Read/Write) access permissions.
- The Administrators role - full (Read/Write) access permissions.
- Publicly - denoted by the presence of the Public entity - with Read-only access permissions.
Configuration of access permissions can be performed through the Vault's browser interface, and also directly from within Altium Designer.
From within the Vault's Browser Interface
To configure access for a project from the Vault's browser interface, from the PROJECTS page of the interface simply click on the project's associated Share control ().
The Manage Permissions window will appear, with all the controls necessary to share the project with other users.
With projects centrally managed in a Vault, sharing with others is simply a case of managing each project's permissions.
Things to be aware of:
- In terms of permissions, a user/role has Read/Write access when the Can Write option is enabled. If this option is disabled, they have Read access only.
- To remove an existing user/role from having shared access to a project, click the associated Remove control (
).
- All users of the Vault will by default be able to see the project. If you want to lock access down to a specific set of users and/or roles, you must remove the Public entity.
- If you remove the Public entity, it can be added back again using the Add Public control. Be aware that doing so wil, by default, grant Read/Write access of the project to all Vault users.
Sharing a Project with a Vault User
To share a project with another Vault user:
- Click the Add User control in the Manage Permissions window.
- In the Add Users window that appears, start typing the full name, username, or email address of a Vault user in the Select Users to be added field, to pop-up a list of matching users. Select the required user from this list. Multiple users can be chosen. To remove a user, simply click the delete cross, to the far right of their name.
- Set the permission for the user(s) using the Permission field. Use the drop-down to choose betwen Read access, or Read/Write access.
- Click the
button once ready, to effect addition of the user(s) and return to the Manage Permissions window.
- Click the
button in the Manage Permissions window.
To edit the permissions for an existing user, simply use the Can Write option in the Manage Permissions window, to toggle between Read/Write access (enabled) or Read-only access (disabled).
Sharing a Project with a Defined Role
You also have the ability to share with roles defined for your Altium Vault. To share a project with another role:
- Click the Add Role control in the Manage Permissions window.
- In the Add Groups window that appears, start typing the name of a role in the Select Roles to be added field, to pop-up a list of matching roles. Select the required role from this list. Multiple roles can be chosen. To remove a role, simply click the delete cross, to the far right of its name.
- Set the permission for the role(s) using the Permission field. Use the drop-down to choose betwen Read access, or Read/Write access.
- Click the button once ready, to effect addition of the role(s) and return to the Manage Permissions window.
- Click the button in the Manage Permissions window.
To edit the permissions for an existing role, simply use the Can Write option in the Manage Permissions window, to toggle between Read/Write access (enabled) or Read-only access (disabled).
From within Altium Designer
Access for a project can be configured directly from within Altium Designer by using the Configure Project Access command. This command can be accessed for the active project, or a focused project:
- Active project - with a source document for the project open as the active document, choose the Project » Configure Project Access command, from the main menus.
- Focused project - access is made from the Projects panel by right-clicking on the entry for the required project and choosing the Configure Project Access command, from the context menu.
The Permissions For - <ProjectName> dialog will open in which you can configure sharing as required.
Configure access to your Managed Project directly from within Altium Designer.
Opening a Managed Project
To work on a managed project, you check it out as a local working copy. This can be performed in two ways:
- Directly from within Altium Designer - use the File » Open Managed Project command. The Open Managed Project dialog will appear, from where you can choose which managed project to open. Only those Managed Projects that have been shared with you (you have permission to access) will be listed, and from across all managed Design Repositories shared with you.
Choose which managed project to open, from within Altium Designer, from those currently shared with you.
- From the PROJECTS page of the Vault's browser interface - click the Open control () associated with the project. From the detailed Project view for the project that is presented, click the button.
After clicking the
button, a dialog will appear asking for confirmation to open
dxp.exe - Altium Designer's underlying executable. Click the
Open dxp.exe button to open the project in the running instance of Altium Designer.
Access the control to open a managed project from its detailed view within the Vault's browser interface.
Editing a Managed Project
To edit the properties of a Managed Project at a later stage, simply click its associated Edit control ().
The Edit Project window will appear. From here, you can change the project's Name and/or Description. All other fields are non-editable, providing information only.
You can edit the Name and Description for a Managed Project at any stage.
Cloning a Managed Project
To clone an existing managed project, access its detailed Project view, then click the button. The Clone Project window will appear.
You can clone a managed project - creating an identical copy of it, along with its working files.
Use the window to set the following for the clone project:
- Name
- Description
- Vault Folder
- Repository Folder
By default, the original project name will be used, simply adding the suffix ' - Copy'.
The cloned project will be made in the same design repository as the original - you cannot change this as part of the cloning process.
After setting the fields as required, click the button - the original project will be cloned, and the clone opened within the interface at the Stream tab of its detailed Project view.
Removing a Managed Project
To remove a Managed Project, simply click its associated Remove control ().
