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 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.

atlas snippets

If an atlas.json file is open, installing dependencies can also be done via the download icon added to the top of the editor.

atlas-dependencies

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.demo-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 would be:

{
    "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.demo-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 first five digits from the download URL. For example, if the URL is "https://community.demo-hclvoltmx.com/marketplace/asset/25265/25264/19371?agent=web", the library is "25265".
- version: a human-readable version number mapping to a release. "latest" is not relevant for Volt MX Marketplace.
- module: the specific extension to be incorporated. For Volt MX Marketplace, this will be the subsequent two sets of five digits from the download URL. For example, if the URL is "https://community.demo-hclvoltmx.com/marketplace/asset/25265/25264/19371?agent=web", the module is "25264/19371". NOTE: This will 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 Foundry development can be accessed by typing foundry-atlas in an atlas.json. For more details, see Volt MX Foundry atlas.json.

.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
        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 their atlas.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 to true, a seti.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 the seti.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 Foundry

If you are deploying an integration service to Foundry, you can package up the code with the build management extension. For more details see Package for Foundry.