Managed Scripts in an Altium Vault

This document is no longer available beyond version 17.1. Information can now be found here: Scripts in a Workspace for version 22

Applies to Altium Designer version: 17.1

 

Altium Designer, in conjunction with Altium Vault (3.0 or later), provides the capability of releasing Script Projects into the Altium Vault where they can then be accessed on a permission basis by Altium Designer users.

In Altium Designer, these Vault-based Script Projects can be opened directly from the Vault, loaded as permanently available projects, used in Custom menu commands, or assigned to Preferences that are controlled by the Vault’s Environment Configuration service.

Script projects are uploaded into a lifecycle-managed revision of a Script Project Item in the Vault, which allows an organization to manage and distribute ratified, custom script projects to Altium Designer users through administrative control. Ranging from simple utility scripts to those performing complex source operations, Scripts can be both a convenient and powerful way of adding functionality to Altium Designer.

Release a Script Project

A Script Project can be directly uploaded to a Script Item in the Vault through Altium Designer's Vaults panel (DXP » Vault Explorer), where the Item is generally created within a suitable Scripts Project folder – of the Scripts Folder Type. If not already available, this is also added through Vaults panel.

Note that the folder’s applied Item Naming Scheme will define the format of the unique ID for each Script Item created in that folder. Normally, this will be set to a suitable, basic Naming Scheme by default, but can be changed to another predefined scheme (or a custom scheme).

Create Script Item

To create a Script Item in the target folder, select the Script Item option after clicking the Add an Item link in the Vaults dialog’s Item area, or from the right-click context menu. The following Create Item dialog offers all properties settings for the new Item, including Comment and Description fields that will help with quick identification of Script Items when searching the Vault.

Add a meaningful Comment and Description to a new Script Item so that Vault searches are more effective – note the Search tab at the bottom of the Vaults panel.
Add a meaningful Comment and Description to a new Script Item so that Vault searches are more effective – note the Search tab at the bottom of the Vaults panel.

When the Create Item dialog is dismissed (OK), the new Script Item is created in the target Scripts folder, where it exists in an initial Planned Revision state until populated with the released Script project.

How Revisions of an Item are named, and how those revisions progress through their Lifecycle States, are determined by the Item's Revision Naming Scheme and Lifecycle Definition, respectively. Again, these should be set to sensible defaults, but can be changed when (or after) the Item is created – but before Script data has been uploaded (released) to that Item Revision.

Upload a Script Project

To release a Script Project into the target Script Item Revision, select the Upload option from the Item’s right-click context menu and browse to the desired local Script Project.

A created Script Item will be in a Planned state until a Script Project is uploaded into the initial Revision, where it will normally progress to a read-only In Production state.
A created Script Item will be in a Planned state until a Script Project is uploaded into the initial Revision, where it will normally progress to a read-only In Production state.

The selected Script Project will be released to the new Item Revision, which will (typically) progress from a Planned to In Production lifecycle state – note that the change in state will depend on the Lifecycle Definition applied to this Item.

In the Vaults panel, select the Details view to see the files contained in the current Script Revision.
In the Vaults panel, select the Details view to see the files contained in the current Script Revision.

To edit a released Script Project, right click on its Item Revision in the Vaults panel and select Edit xxx (where xxx is the selected Revision’s name). This will open the current (latest) version in Altium Designer where it can be edited as required, then Released back to the Vault as a new Revision using the Release to Vault command – available from the Project Name right-click context menu.

Using a Released Script Project

A Vault-hosted, managed Script Project can be used in several different ways in Altium Designer, where the methods range from simple direct access to imposing Script Preferences as part of an applied Environment Configuration.

Run a Script

To run a Vault-based accessible script directly in Altium Designer (DXP » Run Script), choose the Browse » From Vault option in the Select Item To Run dialog. The managed Script Project selected in the following Choose Item dialog will be opened from the Vault in the Select Item To Run dialog, where it can be Run in the usual way.

Choose to run a script from a Vault source, rather than a local source, by selecting the From Vault option in the Select Item to Run dialog.
Choose to run a script from a Vault source, rather than a local source, by selecting the From Vault option in the Select Item to Run dialog.

Install a Script

Altium Designer allows any number of Script Projects to be installed on a permanent basis, so their functionality becomes available at all times, for all Altium Designer sessions. This feature is included as part of Altium Designer’s Preferences (DXP » Preferences), and is located on the Global Projects page in the Scripting System section.

To install a Script Project from the Vault, select Install from Vault from the Install button options. Select the desired vault-hosted Script from the following Choose Item dialog, and dismiss the dialog (OK) to install the Script Project.

Installed Scripts are always available in Altium Designer, and are configured in the Global Projects page of the Preferences dialog.
Installed Scripts are always available in Altium Designer, and are configured in the Global Projects page of the Preferences dialog.

The installed Script Project will be available to Altium Designer whenever a User is signed in to the Vault with suitable credentials. Note that the installed Script Project is listed by its location or 'path' in the Vault, and its name reflects the Script Item ID that hosts the script project data.

A Managed Script installed from an Altium Vaults is listed by its Vault path and Item ID name.
A Managed Script installed from an Altium Vaults is listed by its Vault path and Item ID name.

The Vault reference links created in the Preferences by an installed Script Project are retained, and therefore will be included if the Preferences file is also released to the Vault.  The resulting Managed Preferences entry in the Vault can be applied as part of an Environment Configuration, which will automatically provide the linked Managed Script to Users in the designated team.

Create a Script Command

In Altium Designer, a Script (either locally or Vault -sourced) can be applied to a menu item with a number of simple steps. This relies on the permanent availability of that Script, which must be installed through the Script Preferences (as detailed above).

A custom Command is created from an installed Script using the Customize feature (DXP » Customize), which via the Edit Command dialog, allows the definition of a new Action based on the Script Process and Parameters. The command Parameters define the full path to the Script and its target Procedure, and are in the form: ProjectName|ProcName>Process.  So for a typical locally-stored Script, this might be:

ProjectName=C:\Design\Scripts\Hello\Hello.PRJSCR|ProcName=DisplayHelloWorld.pas>ShowAMessage

For a Managed Script Project hosted in the Vault however, the path, and therefore the command’s Parameters entry must point to the correct Vault location – which is based on the Script Item’s GUID reference. So this reference link must be obtained before attempting to create the new Script command entry.

To capture the correct Parameters for a Script installed from the Vault, open the Select Item To Run dialog (DXP » Run Script), right-click on the desired procedure in the Script and select Copy script parameters. This will copy the entire path, process name and procedure to the Clipboard.

Select the required process/procedure in the script project before copying the Vault command Parameters.
Select the required process/procedure in the script project before copying the Vault command Parameters.

The new Script command can now be created in the Edit Command dialog – select DXP » Customize, and then the button in the following Customizing DefaultEditor Editor dialog. In the Edit Command dialog, paste the copied script parameters into the Parameters field, then complete the other fields (Caption, Image, Shortcuts etc) as required.

Paste the copied Vault Script parameters in the editor's Parameters field, then proceed as you would when creating a command from a locally-sourced Script.
Paste the copied Vault Script parameters in the editor's Parameters field, then proceed as you would when creating a command from a locally-sourced Script.

From the Customizing DefaultEditor Editor dialog, the completed script command can be dragged to a suitable Altium Designer Toolbar or Menu and run as needed.

Note that since the Command's Script is sourced from the Altium Vault, it will be only available when the User has signed in to the Vault with the correct credentials.

A menu command created from a Vault-based Script is functional when the User is signed in to its host Vault.
A menu command created from a Vault-based Script is functional when the User is signed in to its host Vault.

Note

The features available depend on your level of Altium Designer Software Subscription.

Content