Workspace Projects

Parent page: Altium NEXUS Server

Altium NEXUS, in conjunction with the Altium NEXUS Server, 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 NEXUS Server 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.
• Advantages 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.
• Ability to share a read-only, browser-based interactive view of a project with other users, via Web Review.

Technically a Managed Project is the combination of meta information stored on the server, along with tight integration with the NEXUS Server's own Version Control service. The typical work flow is as follows:

1. A user creates a new managed project via the NEXUS design client's Create Project dialog, from the NEXUS Server's browser-based interface, or by converting an existing project on the design client side. During creation, that user defines the project's name, description, and design repository.
2. Access to the project is defined and managed in the NEXUS Server's browser-based interface, or directly within the NEXUS design client.
3. All collaborators select the project for opening (either from within design client or from the server's browser interface) after which it is automatically checked out as design files.

Creating a New Managed Project

There are three main ways in which a Managed Project can be created:

• Creation of a new project from the NEXUS Server's browser-based interface, or from within the NEXUS design client.
• Making an existing, non-managed project available on the Server from within the NEXUS client – that is, converting an unmanaged project to a managed project.
• Cloning an existing Managed Project through the NEXUS Server's browser-based interface, or by cloning a project from the NEXUS client Projects or Explorer panels.

The following sections take a closer look at these methods of creating a Managed Project.

Through the NEXUS Design Client

From within the Altium NEXUS design-side client, a new Managed Project can be created using the Create Project dialog (File » New » Project):

1. Select the entry for your NEXUS Server from the dialog's LOCATIONS options (it will appear with the name you have specified for it, on the Admin – General page of the server's browser interface) – you must be signed in to the NEXUS Server with administrator privileges to access the server naming option.
2. Enter a Project Name in the Create Project dialog and optionally, a project Description.

3. The Project Type column allows you to select the type of project that is being created, and if an available Project Template will be used. The list of templates for each project type includes all compatible Project Templates that are available in the server.
4. The Repository drop-down menu (if present) will list all Design Repositories managed through the NEXUS Server'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 a 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.
5. Use the Folder field to specify where the folder for the project – within the server's folder structure – is to be created. The default path for new NEXUS Server projects is specified on the Admin – Settings – Projects page of the server's browser interface.
6. 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 in the System – Default Locations page of the Preferences dialog.
7. Use the button to add parameter Name-Value pairs to the Parameters list. These Managed Project parameters are saved in the server with the new project, and can be edited within the server. By contrast, Project type parameters are saved in the project file (*.PrjPcb), and can be edited on the NEXUS design side. Both parameter types may be used as Special Strings in the design client.

The button associated with each entry can be used to browse to and select an alternative path/repository.

Setting up to create a new Managed Project from within NEXUS, 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 , 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 as being Scheduled for addition, denoted by the associated icon.

Right-click on the project name in the Projects panel and choose the Save to Server command or the Version Control » Commit Whole Project command – the former command also is available from the File menu. You will be presented with the Commit to Version Control dialog. Select the files you wish to commit to the Design Repository and click Commit and Push (or Commit for a target SVN repository). Once added, 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.

Commit the newly created Managed Project to the target Design Repository.

In addition, an entry for the project will appear on the Projects Management page (Projects) of the NEXUS Server's browser interface.

The newly-created Managed Project, evident on the Projects page of the server's browser interface.

Through the NEXUS Server Browser Interface

A Managed Project can be created directly through the Altium NEXUS Server's browser interface:

1. Sign in to the interface and select the Projects menu option to access the Projects Management page. Any previously created projects will be listed here.
2. Click the button at the top of the page to open the Project creation dialog window.

If there are any active process definitions available for the Project Creations process theme – defined on the Project Creations tab of the Processes page of the server's browser interface – then this button will appear as . Click to access and choose the required process. The corresponding workflow for the chosen process will then be invoked.

3. The window will initially present in simplified view. Enter the desired name for the project, a description (if needed), and choose a suitable Managed Project Template from the Templates drop-down menu.

4. To access more controls click the  button. The following fields will present:
   1. Vault (Server) Folder – use this field to specify where the folder for the project is to be created within the server's folder structure. By default, this will be Projects\<ProjectName>. The default path for new projects is specified on the Admin – Settings – Projects page of the NEXUS Server's browser interface.
   2. Repository – this field will list all Design Repositories managed through the Altium NEXUS Server'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. By default, the Versioned Storage (Git-based) repository will be selected.
   3. 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. If the Versioned Storage (Git-based) repository is chosen, this field will not be presented.

Defining a new Managed Project directly through the NEXUS Server's browser interface.

After defining the new project as required, click – the new project will be created. The Projects Management page listing will now show an additional entry for your newly-created project.

An additional Managed Project, created through the browser interface. Click the Projects entry in the nav tree to access the Projects Management view listing.

Conversion of an Existing Non-Managed Project

You can also create a Managed Project from an existing non-managed one by converting the latter to the former. To do this, open the existing non-managed project as normal in the NEXUS design client, then right-click on its entry in the Projects panel and use the Make Project Available on Server command from the context menu.

The Make Project Available on Server command opens the Make Available on Server dialog, which allows you to determine the project's name and its description. By default, the name will be that of the original (source) project.

Further settings are available by opening the Advanced options:

• The target design Repository in the NEXUS Server that you are currently signed into. Choose from all managed repositories shared with you, and that are defined through the server's Version Control service (on the VCS page (Admin – VCS) of the server's browser interface). This option is not shown when the default Git-based repository (Versioned Storage) is the only one available.
• The Repository Folder within an SVN repository when this type is selected. This option is not available when the default Versioned Storage (Git-based) repository is used.
• The server Folder entry represents the target path for the new project entry within the server's folder structure. By default this will be Projects\<ProjectName> but may be edited to suit, where the server Folder setting will also define the location in which data for the project will be released when using the NEXUS client Project Releaser.

The button associated with each entry can be used to browse to and select an alternative path/repository.

Convert an existing project to a Managed Project.

With the properties for the Managed Project defined as required in the Make Available on Server dialog, click OK. The project and files will be committed to the target Design Repository, with the Projects panel reflecting the fully synchronized state that exists between the files in the repository and the local working copy – as indicated by the icons in the Projects panel.

The newly-converted Managed Project will subsequently be available in the Projects Management page listing of the NEXUS Server's browser interface.

The converted project is added to the list of centrally-managed projects.

Working with GitHub

Using the GitHub platform as an external version control system (VCS) is a popular way to host and share design projects, and is easily integrated with the NEXUS Server through Altium NEXUS. The existing external VCS arrangement is synchronized with the NEXUS Server which allows you to benefit from its advanced data management and collaboration features.

How you normally work with GitHub itself will vary depending on company practices or simply the Git tools you have at hand. In general however, a design project is created in a local Git repository and then Pushed to a GitHub (remote) repository, or an existing project is Cloned to a local repository from GitHub. Once in the local Git repository, the project can be opened in Altium NEXUS and made available to the NEXUS Server (Make Project Available on Server), as outlined above.

GitHub Protocols

While there is a range of data transfer protocols offered by the Git VCS, Altium NEXUS currently supports the HTTP/HTTPS protocol only for connections between a local Git repository and its remote master repository. In practice, the applied protocol is set by the URL prefix specified for the remote repository connection – https://<remote repository>, ssh://<remote repository>, git://<remote repository>, and so on.

GitHub supports both the SSH and HTTPS protocols, and recommends using HTTPS URLs for connections.

► See Which remote URL should I use? on GitHub for more information.

If your external VCS system is bound to a protocol other than HTTPS, such as a GitHub SSH connection, this will be preset in a repository that has been cloned from the remote. As this protocol is incompatible with Altium NEXUS, an error will be thrown when attempting to integrate the project with NEXUS. If you are unsure of the remote URL protocol that is used for a local Git repository, this can be checked using the git remote - v command.

Use the Git Bash command line interface to check a repository's remote URL setting.

The repository can be reconfigured for a different URL, such as the HTTPS protocol to enable compatibility with Altium NEXUS, by using the git remote set-url <name> <URL> command, where the URL's prefix specifies the protocol type.

Changing the remote repository connection URL protocol and then confirming with the remote command.

Browsing Managed Projects

Managed Projects are available to browse from the Projects Management page of the NEXUS Server's browser interface, accessed from the Projects option in the main menu. Use the upper and buttons to change the view between its Preview and List modes, respectively.

The Projects Management page of the NEXUS Server's browser interface. Hover over the image to see the alternative List view.

The view's project entries are automatically sorted by Last modified date, with the most recently modified project appearing first in the list. Click the button to change to sorting by project Name, and click again to toggle between ascending and descending order.

The List mode view () can be sorted by any data column by clicking on its header. Click again to toggle the order sort between ascending and descending order.

The Projects Management view provides Properties and Activities data that relate to the selected project, available in the view's right-hand sidebar pane.

The sidebar pane information includes: Properties tab: General Info – a summary of the project's state and user associations. Description – the description text entered during project creation or editing (see Edit). Releases – a dated list of project releases and their constituent package data. Additional Info – metadata extracted or calculated from the project source documents. Preview – graphical representations of the project's Schematic and PCB documents. Activity tab – a chronological list of active or completed process workflows associated with the project.

For each project, the following operations also are provided by the buttons at the top of the view (and detailed in the linked sections that follow):

• Share – access controls with which to configure project access permissions.
•  Activities – menu access to the process activities available to the project.
•  Functions – menu access to project functions. Also available from the  button of a selected project when in Preview mode:
  • Open – open the project in its detailed CAD-centric view. Equivalent to clicking (Preview mode) or double-clicking (List mode) on a project name entry.
  • Edit – edit the project in terms of its Name, Description and server Parameters.
  • Clone – create a renamed identical copy of the project.
  • Watch/UnWatch – follow/unfollow a project's activity by receiving related notifications (updated, released, etc) on the main Home and Stream pages.
  • Remove – remove the project, and optionally its system-level structure, from the server.

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. A managed project – newly created or converted – is shared, by default, with the following:

• The Owner of the project, which is usually the designer who created it (or made it available on the server): full (Read/Write) access permissions.
• The Administrators role group: full (Read/Write) access permissions.
• All server Users – denoted by the presence of the Anyone entity: Read-only access permissions.

Configuration of access permissions can be performed through the NEXUS Server's browser interface, and also directly from within Altium NEXUS.

From within the NEXUS Server's Browser Interface

To configure access for a project from the NEXUS Server's browser interface, select the project entry on the Projects Management page (Projects on the main menu) and click the button to access the Manage Permissions window. This offers all the controls necessary to share the project with other users.

With projects centrally managed in a NEXUS Server, sharing with others is simply a case of managing each project's permissions.

Within the Manage Permissions window:

• A user/group 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/group from having shared access to a project, click the associated Remove control ().

Things to be aware of:

• By default, all users of the NEXUS Server will be able to see the project. If you want to lock access down to a specific set of users and/or groups, you must first remove the Anyone entity.
• If you remove the Anyone entity, it can be added back again using the Add Anyone control. Be aware that doing so will, by default, grant Read/Write access of the project to all server users.
• The owner of a project has permanent Read/Write access.
• The signed in user must have full Write access to a project in order to access and change its permissions. The exception is Administrators, who have full access to project permission settings.

From within Altium NEXUS

Access for a project can be configured directly from within the Altium NEXUS design client by using the Share command. This command can be accessed by:

• Clicking the button in the top margin.
• Selecting Project » Share on the main menu,
• Right clicking on the project name in the Projects panel and choosing the Share option from the context menu.

The Share <ProjectName> dialog will open in which you can configure sharing as required.

Configure access to your Managed Project directly from within the NEXUS design client.

Managed Project Activities

The Altium NEXUS Server offers the unique capability of applying configurable Process Workflows to Managed Projects in order to perform tailored tasks such as performing design reviews and creating new projects. Processes and their underling Workflows are created and configured by a server administrator, and when enabled, become available to users of both the NEXUS design client and the NEXUS server browser interface.

► See Creating & Managing Processes for more information.
► See Performing Design Reviews for information on these processes in the NEXUS design client.

From a user perspective, Process Workflows and their inherent steps are considered as Activities. Available Activities can be invoked by users, and their workflow steps completed by assigned users as a sequence of tasks – available through the Tasks page.

Select the menu on the Projects Management page (Projects) and choose from the available Processes to initiate an activity for the currently selected project. Complete the required fields and options in the following process form windows, and then start the process ().

Workflow Tasks are then created for the user, or users, assigned to the Activity. A task that applies to a signed in user will appear in their Tasks page, where it can be acted upon to progress the Workflow to its next stage.

Note that when an Activity has been assigned to a Role Group – Engineers for example – a related Task becomes available to all members of that group, and also any individual users that have been assigned to the Activity – here, user Keith. In such cases any of these users can assign the Task to themselves (), and then complete the step and submit the result ().

Managed Project Functions

Functional operations associated with projects are available from the menu on the Projects Management page, and include the ability to open, edit, clone, watch and remove a managed project. The menu also is available from the button of a selected project when in Preview mode:

Open a Project

Select the Open option from the menu to open a project into its manufacturing orientated CAD-centric view, encompassed in the browser interface Projects page. The page provides access to several tabbed sub-views:

• Design – navigate and interact with the project's design documents, inspect object properties and place review comments. The view applies to the current (latest) project revision, and uses the Web Review interface.
• BOM – view the source project's Bill Of Materials information.
• Manufacturing – open a specific project Release in the Manufacturing Portal view, which in turn provides sub-views for Fabrication, Assembly and BOM data, and also the ability to download release data into a manufacturing Build Package.
• Activities – view active or closed Process workflow Activities that apply to the current project.

Open the server's CAD-centric project view from the NEXUS design client by selecting a project in the Explorer panel navigation tree and clicking the button.

► See Management of a Specific Project for more information.

Edit a Project

To edit the properties of an existing project in the NEXUS Server, select its entry on the Projects Management page (Projects) and then the Edit option from the menu. In the following Project Editing window you can change the project's Name, Description and manage server Parameters entries.

Click the  button in the Project Editing window to expose additional property fields, which include read-only Vault/Repository storage information. Select the Parameters control to access and add (), edit, or remove () parameter Name/Value pairs. These are saved in the server with the project, and may be used as Special Strings in the NEXUS design client – access from the Properties panel with a placed Text String selected in the design workspace.

In the NEXUS design client, edit a selected project's properties in the Edit Project dialog, opened from the menu Edit command in the Explorer panel.

Clone a Project

To clone (duplicate) an existing managed project, select its entry on the Projects Management page (Projects) and then the Clone option from the menu. Use the Project Cloning window to set the name and description for the cloned project – by default, the original project name will be used with a - Copy suffix.

Click the button to expose additional property fields, which include the target server folder and read-only Repository information. The target folder setting will automatically match the project name unless manually specified.

A project can be cloned in the NEXUS design client from the button in the Explorer panel, or by right-clicking on a project name in the Projects panel and choosing the Clone option from the context menu.

Watch a Project

To 'watch' – receive notifications regarding – project in the NEXUS Server, select its entry on the Projects Management page (Projects) and then the Watch option from the menu.

When you follow (watch) a project, you will receive notifications related to the project (such as update, release and permission change messages) on the Home and Stream pages of the browser interface. The creator of the project will automatically be set to watch that project. When enabled, the command will change to UnWatch – select to stop following the project and cease reception of notifications for events relating to that project.

Remove a Project

To remove (delete) an existing managed project, select its entry on the Projects Management page (Projects) and then the Remove option from the menu. The Delete Project window that follows offers three deletion levels of increasing depth:

• – remove the project files but not the server folder and any associated content it contains, such as release data. The project repository is archived and can be recovered at an IT level.
• – remove the project folder with all files and data it contains.
• – remove the project folder and all content including the project repository folder.

Hover over the buttons for popup tooltip information. Note that when a button is clicked the project is immediately removed, based on the constraints that apply to that button option.

To remove a Managed Project from within the NEXUS design client, access the Delete Project dialog by choosing the Remove option from the menu in the Explorer panel.