Skip to content

Lab 03 - Using VoltScript Extensions and Dependency Management

Duration 25 min

What you will learn

You'll learn how to use dependency management, how it creates a seti.ini, how to use UseVSE to include the VoltScript Extensions, and how to do basic JSON parsing.

Prerequisites

  • Lab 02 completed

Steps

atlas-settings.json

Info

As with other dependency management systems, dependencies are downloaded into a local repository in your user directory. For Maven, that is .m2. For Rust, it's .cargo. For VoltScript, it's .vss. This allows dependencies to be built from local artifacts, if possible, rather than always going to the internet.

Within the .vss directory, an atlas-settings.json file holds a single JSON objects containing JSON objects whose label matches a repository in the atlas.json. Each object contains the type and the credentials for authenticating to repositories. For "github" types, this is a Personal Access Token. For "marketplace", this is the username and password. For "webserver" types, if the web server is unauthenticated, the credentials should be an empty string. If authenticated, this is Base64 encoded username and password. If the value is in the format "${env.FOO}", VoltScript Dependency Manager will retrieve an environment variable based on the name defined (here, "FOO"). This avoids the need for credentials to be hard-coded.

Warning

There is no intention to support retrieving credentials from credential stores.

  1. From the Command Palette in VS Code, run "VoltScript: Run Dependency Setup".
  2. In Windows Explorer or a terminal, navigate to your user directory and open the .vss directory.
  3. Create a text file called atlas-settings.json and open the file in Visual Studio Code.

  4. Create a JSON object.

    Info

    Unlike the atlas.json, you won't get content assist immediately. The atlas-settings.json will be a JSON object, containing JSON objects for each repository, each with a label. So you will need to add a label whose value is a JSON object, and that JSON object will provide content assist. Alternatively, there are snippets available by typing "atlas-settings" that will create JSOn objects with all possible options.

  5. Add a label "hcl-github". For its value, create a JSON object. Required properties for it will appear in the Problems view.

  6. Set type to "github".
  7. Set token to your GitHub Personal Access Token.
    1. If you don't have one yet, follow GitHub's documentation for creating a GitHub Person Access Token. The value will begin "ghp_". For more details see how-to guide.
  8. Add a label "volt-mx-marketplace". For its value, create a JSON object.
  9. Set type to "marketplace".
  10. Set authUrl to "https://accounts.auth.demo-hclvoltmx.net/login".
  11. Set username and password to your credentials for Volt MX Marketplace.
    1. You can create an account or check your login credentials at Volt MX Marketplace. If you are creating a new account, make sure to successfully log in to activate the account before using the credentials in dependency management.
  12. The atlas-settings.json should look like this:
{
    "github": {
        "type": "github",
        "token": "YOUR_TOKEN"
    },
    "volt-mx-marketplace": {
        "type": "marketplace",
        "username": "YOUR_USERNAME",
        "password": "YOUR_PASSWORD",
        "authUrl": "https://accounts.auth.demo-hclvoltmx.net/login",
    }
}

Info

VoltScript Dependency Manager can have two repository types, "webserver" and "github". A GitHub repository requires a Personal Access Token, so the atlas-settings object for the "github" type takes a "token" element. A Web Server repository requires Base64 credentials, so it takes a "credentials" element.

atlas.json

  1. Click File → Open Folder.
  2. Create a new folder in your user directory called "lab-03".
  3. Right-click in the empty pane and select New File from the context menu.
  4. Name the file "atlas.json".
  5. Type an opening curly brace "{" and press Enter. VS Code will automatically add the closing curly brace "}".
  6. Set name to "lab03".
  7. Set version to "1.0.0".
  8. Set description to "Lab Number 3".
  9. Add the authors array. Add an array element with your name.
  10. Set sourceDir as "src".
  11. Set testDir as "test".
  12. Set mainScripts as "main.vss".
  13. Set libsDir as "libs".
  14. Set vsesDir as "vses".
  15. Add repositories array.
    1. Add a JSON object. Required properties for it will appear in the Problems view.
    2. Set id to "volt-mx-marketplace".
    3. Set type to "marketplace".
    4. Set url to "https://community.demo-hclvoltmx.com/marketplace/asset".
    5. Add another JSON object. Required properties for it will appear in the Problems view.
    6. Set id to "hcl-github".
    7. Set type to "github".
    8. Set url to "https://api.github.com/repos/HCL-TECH-SOFTWARE".
  16. Add dependencies array. Add a JSON object. Required properties for it will appear in the Problems view.
    1. Set library to "voltscript-testing".
    2. Set version to "1.0.1.
    3. Set module to "VoltScriptTesting.vss".
    4. Set repository to "hcl-github".
  17. Add another JSON object to the dependencies array.
    1. Set library to "voltscript-json-converter".
    2. Set version to "latest".
    3. Set module to "VoltScriptJsonConverter.vss".
    4. Set repository to "hcl-github".
  18. Add vseDependencies object. This is an object, because each element needs a label that will be used in the UseVSE statement.
    1. Add a label "StreamVSE". For the value, add a JSON object.
      1. Set library to "25284".
      2. Set version to "1.0.0".
      3. Set module to "25283/19424".
      4. Set repository to "volt-mx-marketplace".
  19. Save the atlas.json. The final atlas.json should look like this:
{
    "name": "lab03",
    "version": "1.0.0",
    "description": "Lab Number 3",
    "authors": [
        "Your Name"
    ],
    "sourceDir": "src",
    "testDir": "test",
    "mainScripts": [
        "main.vss"
    ],
    "displayName": "My Way Cool Project",
    "libsDir": "libs",
    "vsesDir": "vses",
    "repositories": [
        {
            "id": "volt-mx-marketplace",
            "type": "marketplace",
            "url": "https://community.demo-hclvoltmx.com/marketplace/asset"
        },
        {
            "id": "hcl-github",
            "type": "github",
            "url": "https://api.github.com/repos/HCL-TECH-SOFTWARE"
        }
    ],
    "dependencies": [
        {
            "library": "voltscript-testing",
            "version": "1.0.1",
            "module": "VoltScriptTesting.vss",
            "repository": "hcl-github"
        },
        {
            "library": "voltscript-json-converter",
            "version": "1.0.0",
            "module": "VoltScriptJsonConverter.vss",
            "repository": "hcl-github"
        }
    ],
    "vseDependencies": {
        "StreamVSE": {
            "library": "25284",
            "version": "1.0.1",
            "module": "25878/20842",
            "repository": "volt-mx-marketplace"
        }
    }
}

VoltScript Dependency Manager

  1. From the Command Palette, run "VoltScript: Install Dependencies".

Info

This runs the VoltScript executable, passing the seti.ini for the VoltScript Dependency Manager. It runs archipelago.vss, the main dependency manager script. It requires four arguments:

  • The directory for the project
  • The location of the atlas.json to build dependencies from
  • The location of the atlas-settings.json
  • A boolean telling the script to force reload from remote repositories

Success

Your project should now have "src", "test", "libs" and "vses" directories.

  • The src directory is empty.
  • The test directory is empty.
  • The libs directory has been populated with VoltScriptTesting.vss and VoltScriptJsonConverter.vss.
  • The vses directory has been populated with ddl and so files for StreamVSE and JsonVSE - JsonVSE is a downstream dependency used by VoltScript JSON Converter, automatically picked up because of its atlas.json.
  • A new file, seti.ini, has been created. This contains mapping for the VoltScript Extensions (VSEs) and will be used for mapping UseVSE statements.
  • A new file, effective-atlas.json, has been added to the root of the directory. This contains the aggregated settings for the project.

Simple Script

  1. Download main.vss and put it in src directory.
  2. Open src/main.vss and review the script.
    • The script starts and then reads the first line of text from command line input using StreamVSE and a new Stream (pipeStream).
    • It then tries to convert the data to JSON using JsonVSE (jsonParser).
    • It then tries to convert the JSON to a Variant array of Person objects using VoltScriptJsonConverter (JsonConversionHelper).
    • It then builds a response JSON object using the Person class's getName() function and pretty-prints the output.
    • If an error occurs, it is printed to the console and (in the finally block) the stream is closed.

  3. From the terminal in Visual Studio Code, run the command:

    VoltScript src/main.vss

  4. Copy the JSON contents to clipboard.

    [{"id":1,"firstName":"Bobby","lastName":"Stodd","email":"bstodd0@ibm.com","gender":"Male"},{"id":2,"firstName":"Leeanne","lastName":"Mortimer","email":"lmortimer1@posterous.com","gender":"Female"},{"id":3,"firstName":"Rochette","lastName":"Santora","email":"rsantora2@unc.edu","gender":"Female"},{"id":4,"firstName":"Missy","lastName":"Prestedge","email":"mprestedge3@nih.gov","gender":"Female"},{"id":5,"firstName":"Cleavland","lastName":"Lortzing","email":"clortzing4@gov.uk","gender":"Male"}]

  5. Paste the JSON from clipboard and press Enter to pass the string into the script. The file is at sampleJson.

Success

You have successfully read in a complex JSON array from the command line, converted it to an array of VoltScript objects with two lines of code, and manipulated the data for a response.

Review

This gives you an idea of a day in the life of a Volt MX Go VoltScript developer. You will use VoltScript Dependency Manager to avoid having to copy and paste dependencies around. You will be writing middleware functions, which will receive input from an Iris app, including parameters and query string information. It will then need to act upon that data, potentially retrieving data from a remote database, and return a JSON response for the Iris app.

In the things to explore, you can change the function so it can be unit tested. Apart from input, there is no external integration, so integration tests are irrelevant. These tests will allow you to prevent regression bugs. The same process can be used to check output for dummy input from the IDE, without running from command line.

The code for the lab is available on GitHub.

Things to explore

Writing Unit Tests

Refactor Code

  1. Create a new file in libs called functions.vss.
  2. Add Option Declare and Option Public.
  3. Add UseVSE "*JsonVSE".
  4. Add Use "../libs/VoltScriptJsonConverter".
  5. Cut the Person class from main.vss and move it to functions.vss.
  6. Create a function called mainFunction(data as String) as JsonObject.
  7. Cut the content inside the main Try block from main.vss and paste it into the function in functions.vss.
  8. The location of the Person class has changed. Update the jsonArrayToObjects() call's third parameter to "functions".
  9. Change the Print response.toString(true) line to Return response.
  10. Back in main.vss, remove Use "../libs/VoltScriptJsonConverter".
  11. Add Use "../libs/functions".
  12. In the Try block, put Print mainFunction(data).toString(true).

Add Unit Tests

  1. Create a new file in test called unitTests.vss.

  2. Paste in the following code:

        Option Declare
    Option Public

    UseVSE "*JsonVSE"
    Use "../libs/VoltScriptTesting"
    Use "../libs/functions"

    Sub Initialize
        Dim testSuite as New TestSuite("Unit Tests")
        Dim data as String
        Dim response as JsonObject
        Dim children as Variant

        data = |[{"id":1,"firstName":"Bobby","lastName":"Stodd","email":"bstodd0@ibm.com","gender":"Male"},{"id":2,"firstName":"Leeanne","lastName":"Mortimer","email":"lmortimer1@posterous.com","gender":"Female"},{"id":3,"firstName":"Rochette","lastName":"Santora","email":"rsantora2@unc.edu","gender":"Female"},{"id":4,"firstName":"Missy","lastName":"Prestedge","email":"mprestedge3@nih.gov","gender":"Female"},{"id":5,"firstName":"Cleavland","lastName":"Lortzing","email":"clortzing4@gov.uk","gender":"Male"}]|
        Set response = mainFunction(data)
        Call testSuite.describe("Check five elements returned").assertEqualsInteger(5, response.childCount)
        children = response.getChildren()
        Call testSuite.describe("Check first element has name").assertTrue(children(0).IsChild("name"))
        Call testSuite.describe("Check first name is Bobby Stood").assertEqualsString("Bobby Stood",_
            children(0).getChild("name").scalarValue, True)
    End Sub

  3. Press Ctrl + Shift + P to bring up the Command Palette.

  4. Select "VoltScript: Save & Run Script" to run the script. Information on the test run will be printed to the Output view, showing that 3 tests were run but 1 failed.
  5. A "unit-test-reports" directory will be added, and a file will be created. Right-click and select Reveal in File Explorer.
  6. Right-click the file and open in a browser.
  7. Click on the failing test and diagnose the problem. The test is checking for "Stood", but the correct value is "Stodd".
  8. Change the assertion and don't forget to also change the test description.
  9. Run the tests again.

Success

The tests should now run successfully.

Other things to explore

  • Investigate content assist for atlas.json and effective-atlas.json.
  • Review what's printed to output for VoltScript Dependency Manager.

  • Look at the effective-atlas.json and understand the structure.

  • Consider how the VoltScript Dependency Manager might impact community involvement. What do you think needs to be included in source control repositories?

  • Consider how the VoltScript Dependency Manager might be used in a CI/CD environment. What do you think should be included / excluded from your source control repositories?

  • Review the seti.ini. Review the use of relative paths. Identify how module is adapted to the actual filename expected.

    Note

    VoltScript Extensions for all operating systems will be added to the relevant directory in yoiur project, ready for deployment on any operating system.