Use VoltScript Build Manager
Info
To get the JSON for existing VoltScript Extensions and Library Modules via dependency management, see the relevant repository or, for HCL-developed code, see the extension references or library module references.
This is delivered as a command line tool called "VoltScript_Archipelago" and a subdirectory called "archipelago". The functions available are:
- VoltScript_Archipelago setup checks for existence of
.vss
directory in the user's directory and creates it, if necessary. - VoltScript_Archipelago installDeps prompts for parameters, builds project directories, and adds dependencies.
Additional functions will be added later for deployment to Volt MX Go Foundry.
VS Code Extension
There is a separate VS Code Extension called VoltScript Build Manager. This provides Command Palette commands for "VoltScript: Run Dependency Setup", which calls VoltScript_Archipelago setup
, and "VoltScript: Install Dependencies", which calls VoltScript_Archipelago installDeps
.
The setup runs automatically, if there is an atlas.json
file in the workspace. It also provides JSON validation for atlas.json
and atlas-settings.json
files, as well as code snippets for both.
If an atlas.json
file is open, installing dependencies can also be done via the download icon added to the top of the editor.
Required files
VoltScript Build Manager uses certain files and directories:
atlas-settings.json
The atlas-settings.json
should be in the .vss
directory and contains a JSON object of repositories and the credentials to use. If the credentials begin with ${env
and end with }
, VoltScript Build Manager retrieves the value from the relevant environment variable. For example, "${env.TOKEN}" would tell the code to retrieve an environment variable called TOKEN.
Each repository element has a label, which matches what's defined in the atlas.json
. It has a type, either "github", "webserver" or "marketplace.
GitHub Personal Access Token
If the type is "github", it should also include "token". Follow GitHub's documentation for creating a GitHub Person Access Token. The value will begin "ghp_". This is required for API access, regardless of whether the GitHub repository is private or public.
If you are connecting to a GitHub Enterprise instance specific for your organization, check the relevant GitHub documentation. Fine-grained Personal Access Tokens may not be available, depending on version installed.
Tip
The minimum permissions required are:
Token Type | Purpose | Access Setting |
---|---|---|
Tokens (classic) | If you need to download releases from public repos only | public_repo |
Tokens (classic) | If you need to download from private or public repos | repo |
Fine-grained tokens | If you need to download releases from public repos only | Public Repositories (read-only) |
Fine-grained tokens | If you need to download releases from public and private repos | Repository permissions > Contents > Access: Read-only |
Web server credentials
If the type is "webserver" and requires authentication, it should also include "credentials", which maps to Base64 basic auth credentials. This is a Base64-encoded string of the username + ":" + password. "Basic " will be automatically prepended by Archipelago when passing the credentials.
If the web server doesn't require authentication, the credentials aren't needed or should be an empty string.
Volt MX Marketplace credentials
If the type is "marketplace", it should include "username", "password" and "authUrl". The authUrl for the main Volt MX Marketplace is "https://accounts.auth.hclvoltmx.net/login".
You will need a login for the Volt MX Marketplace. Make sure you've tested successfully logging into the web interface before using it for dependency management.
Note
You will be prompted to change your password periodically. Make sure you do so, or your account will expire.
Sample
A sample atlas-settings file sould look something like this:
{
"hcl-github": {
"type": "github",
"token": "${env.TOKEN}"
},
"my-web-server": {
"type": "webserver",
"credentials": "${env.CRED}"
},
"volt-mx-marketplace": {
"type": "marketplace",
"username": "${env.USERNAME}",
"password": "${env.PASSWORD}",
"authUrl": "https://accounts.auth.hclvoltmx.net/login"
}
}
atlas.json
The atlas.json
file is used to define a project's metadata as well as dependencies and the repositories in which they reside. It's intended to be included in source control for the project so it does not include any credentials for accessing repositories. For more details, see How to Structure an atlas.json. For dependency management, it's only important to reference certain elements in atlas.json
:
- repositories: an array of repository objects. The repository contains three properties:
- id: used to cross-reference with the atlas-settings.json.
- type: currently only "github" and "webserver" are supported.
- url: base URL for API calls to the repository. See below for more details how this is used.
- dependencies: an array of dependency objects mapping to VoltScript files to use. The dependency contains three properties:
- library: the group under which the .vss files and their own atlas.json are grouped.
- version: an explicit version number mapping to a release, or "latest" to also retrieve the most recent.
- module: the specific file to be incorporated.
- repository: an optional property mapping to a repository ID. If used, Archipelago will look in that repository first.
- vseDependencies: an object of extension dependency objects mapping to extensions to use. The extension dependency is a JSON object whose label is the name you intend to use in the
UseVSE
statement, and which has three properties:- library: the group under which the VoltScript Extension(s) are grouped. For Volt MX Marketplace, this is the title of the asset as found in the breadcrumbs when manually navigating to the extension on Volt MX Marketplace. For HCL extensions, this will be the VSE name followed by " VoltScript Extension", e.g. "JsonVSE VoltScript Extension".
- version: a human-readable version number mapping to the asset version, e.g. "1.0.1". "latest" is not relevant for Volt MX Marketplace.
- module: the specific file to be downloaded. For Volt MX Marketplace, this is the VSE name in lowercase, e.g. "jsonvse". NOTE: This will no longer change with every release.
- repository: an optional property mapping to a repository ID. If used, Archipelago will look in that repository first.
- sourceDir: the directory name, relative to the root of the project, in which to store VoltScript files for main execution.
- testDir: the directory name, relative to the root of the project, in which to store VoltScript files for running unit and integration tests.
- vsesDir: the directory name, relative to the root of the project, in which to store VoltScript Extensions. If omitted, extensions are put in the root of the project.
- libsDir: the directory name, relative to the root of the project, in which to store the VoltScript Library dependencies. If omitted, the VoltScript files are put in the root of the project.
- mainScripts: an array of files that are main runnable scripts.
- unitTestScript: an array of files that are unit test runnable scripts.
- integrationTestScripts: an array of files that are integration test runnable scripts.
Note
A starter atlas.json with all options annotated can be accessed by typing atlas
in an atlas.json. A starter atlas.json specific to Volt MX Go Foundry development can be accessed by typing foundry-atlas
in an atlas.json. For more details, see Volt MX Go Foundry atlas.json.
VSE Extensions
In EA1 and EA2, it was only possible to download VSEs by using the numeric portions of the file download URL, e.g. library as "25265" and module as "25877/20841". The module changed for each version, because it corresponded to a specific file download. This required the Volt MX Marketplace repository URL to be "https://community.hclvoltmx.com/marketplace/asset".
From EA3, a different download URL from Volt MX Marketplace is supported. For this, the library is the asset title, e.g. "JsonVSE VoltScript Extension". The module is the asset filename when downloaded, minus the file suffix, e.g. "jsonvse". This requires the Volt MX Marketplace repository URL to be "https://community.hclvoltmx.com/marketplace". Note that unlike EA1 and EA2, this does not have "/asset" on the end.
If the VSE library and extension are numeric, you must have the repository URL as "https://community.hclvoltmx.com/marketplace/asset". If it is the more human-readable format mapping to the VSE name, you must have the repository URL as "https://community.hclvoltmx.com/marketplace". This format is the preferable option and there has been limited usage of EA1 and EA2, so the repository ID has not been changed. Documentation and the latest versions of all VoltScript Library Modules have been updated to use it.
Warning
All affected VoltScript Library Modules have had new releases. These are:
- VoltScript JSON Converter, version 1.0.4.
- VoltScript Collections, version 1.0.4.
- VoltScript VoltMX Middleware, version 1.0.4.
Ensure you are using at least these versions, or there may be errors downloading downstream dependencies from "https://community.hclvoltmx.com/marketplace".
.vss Directory
Dependencies will be stored centrally in a .vss
directory in the user's directory. This automatically gets created by the VS Code extension. They are divided into a subdirectory for the library, a subdirectory for the version, and the relevant module files. If the version is "latest", they are also copied to a sub-directory with the actual version number. So for VoltScript Testing Framework, this might be:
.vss
voltscript-testing
latest
VoltScriptTesting.vss
version.txt
1.0.0
VoltScvriptTesting.vss
For Volt MX Marketplace, the module downloads a specific version. There is no option for "latest". It downloads a main zip and extracts as platform-specific zips. For the jsonvse example earlier, the directory structure would be:
.vss
JsonVSE VoltScript Extension
1.0.0
JsonVSE.zip
JsonVSE-win64.zip
jsonvse-linux-x64.zip
These directories are used to avoid downloading dependencies from the internet every time.
Installing dependencies
Running dependency management is done using VoltScript_Archipelago installDeps
, the Visual Studio Code command "VoltScript: Install Dependencies" or the icon at the top of the atlas.json's editor. It prompts for four parameters:
- root directory of the project to add dependencies to
- location of the
atlas-settings.json
- location of
atlas.json
to run against, which typically is in the root of the project, but could be elsewhere -
true/false to force download from remote repositories
If false, dependencies will be copied from local
.vss
directory, if available. If true, the relevant dependencies in the.vss
directory will be re-downloaded.
Dependency management will:
- Check for and, if required, create the
.vss
directory. - Create directories for sourceDir, testDir, libsDir and vsesDir properties.
- If not found locally or force is set to
true
, download VoltScript module dependencies in dependencies and theiratlas.json
files, if they exist, to the relevant file structure under the user's.vss
directory. - If not found locally or force is set to
true
, download VoltScript extensions in VSEDependencies to the relevant file structure under the user's.vss
directory. - If not found locally or force is set to
true
, download any required downstream dependencies. - Copy the dependencies to the relevant libsDir or vsesDir.
-
If
seti.ini
does not exist or force is set totrue
, aseti.ini
will be created for any VoltScript extensions.Note
If you add new VoltScript Extensions, delete the
seti.ini
before running dependency management to automatically update theseti.ini
. -
If no libsDir is set, sync between sourceDir and testDir, any
.vss
files not included in mainScripts, unitTestScript and integrationTestScripts. However, best practice is to put shared.vss
libraries into the libsDir. -
Create an effective-atlas.json with verbose details of actual versions, actual locations, and actual repositories used. This can be used to troubleshoot unexpected behavior.
Note
effective-atlas.json should be excluded in your .gitignore.
Troubleshooting
If the VoltScript Dependency Manager fails, review the information printed to the console. An atlas-settings.json will be required for dependencies pulled from GitHub or from a web server that requires authentication. The dependencies will be downloaded to the .vss directory in the user's home before being copied to the project. If using a dev container, this will be the user's home in the container.
Package for Volt MX Go Foundry
If you are deploying an integration service to Volt MX Go Foundry, you can package up the code with the build management extension. For more details see Package for Volt MX Go Foundry.