Skip to content

Foundry Lab 01 - Hello World Integration Service

Duration 20 Min

What you will learn

You'll learn how to create a simple integration service to return a JSON object including a message element that says "Hello World".

Prerequisites

Steps

atlas-settings.json

You will need an atlas-settings.json, as created in Lab 03.

atlas.json

  1. Click File → Open Folder.
  2. Create a new folder in your user directory called "foundry-lab".
  3. Right-click in the empty pane and select New File from the context menu.
  4. Name the file "atlas.json".
  5. Type "foundry-atlas" and accept the snippet.
  6. Set name to "foundry-lab".
  7. Set description to "Simple Hello World Foundry Lab".
  8. Set displayName to "foundry-lab".
  9. Complete publisher and authors.
  10. Delete repo and library elements.
  11. Set version to "1.0.0".
  12. Change array element in mainScripts to "helloWorld.vss"
  13. Delete unitTestScripts, integrationTestScripts, testDependencies, and vseDependencies elements.

  14. Save the atlas.json.

    The final atlas.json should look like this: 
    {
    "name": "foundry-lab",          // REQUIRED: Enter a short name for your VoltScript project, e.g. "Demo1"
    "description": "Simple Hello World Foundry Lab",    // REQUIRED: Enter a longer description, e.g. "My first demo project"
    "displayName": "foundry-lab",  // A longer name to refer to the project, e.g. "Demo 1"
    "license": "Apache 2.0",    // A license to publish the project under.
                                // If you want this to be used by others, Apache 2.0 or MIT are recommended
    "publisher": "HCL America, Inc.",   // Copyright owner
    "authors": [        // REQUIRED: An array of authors, can be names or emails
        "Paul Withers"
    ],
    "version":"1.0.0",  // REQUIRED: Current version for this project, used with dependency management to find the modules
    "sourceDir": "src", // REQUIRED: Directory where mainScripts are located
    "testDir": "test",  // Directory where unitTestScripts and integrationTestScripts are located
    "libsDir": "libs",  // Directory where VoltScript Library Modules and shared scripts are located
    "vsesDir": "vses",  // Directory where VoltScript Extensions are located
    "mainScripts": [    // REQUIRED: Main scripts with Sub Initialize. Used to sync any additional files between
                        // sourceDir and testDir, if libsDir not set
        "helloWorld.vss"
    ],
    "repositories": [       // Repositories in which to search for any dependencies
        {
            "id": "hcl-github",     // REQUIRED: Unique ID matching "repository" in a dependency in this file.
                            // Also matches label of a JSON object in atlas-settings, which gives any credentials to use to access this repository
            "type": "github",   // REQUIRED: Currently "github" or "webserver" are supported
            "url": "https://api.github.com/repos/HCL-TECH-SOFTWARE" // REQUIRED: Base URL of the repository
        }
    ],
    "dependencies": [
        {
            "library": "voltscript-voltmx-middleware",  // REQUIRED: Folder to be appended to the base URL when dependency management tries to download modules
            "version": "1.0.0",  // REQUIRED: Version number of modules to download. Currently only supports explicit version or "latest"
            "module": "VoltMXObjects.vss",   // REQUIRED: Filename of a VoltScript Library Module to download
            "repository": "hcl-github"
        }
    ]
}

VoltScript Dependency Manager

  1. From the Command Palette, run "VoltScript: Install Dependencies".
  2. Enter the project directory, confirm atlas-settings.json and atlas.json locations.

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 VoltMXObjects.vss and VoltScriptCollections.vss. VoltScriptCollections is a downstream dependency of VoltMXObjects.
  • The vses directory has been populated with ddl and so files for ContextVSE and JsonVSE - these are downstream dependencies used by VoltMXObjects, 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.

helloWorld.vss

  1. Create a file "helloWorld.vss" in src directory.
  2. Type "foundry" and accept the Foundry Boilerplate snippet.

  3. Between the two comment blocks, enter the following code:

    Call VoltMxResult.result.insertValue("message", "Hello World!")

  4. Save the file.

Success

A message element with the value "Hello World!" is added to the result's JSON object.

Package for Foundry

  1. From the Command Palette, run "VoltScript: Package for Foundry".
  2. Enter the project directory, confirm atlas.json locations and continue with nothing entered for additional files to package.

Success

A file is created in the root of the project called "foundry-lab.1.0.0.zip". The zip name comprises the project name and the project version from the atlas.json.

Test with mock Foundry payload

Info

At this point, you would push the zip to Foundry. But Volt MX Go Foundry with VoltScript is not yet publicly available. You will need to test manually.

  1. In helloworld.vss, add a private function call getMockData(), returning a string.

    The function should look like this:

    Private Function getMockData() as String
    Return |{
    "projectDir": "ADD PROJECT DIRECTORY PATH HERE",
    "result": {},
    "request": {
    "headers": {
        "content-length": "402101",
        "cookie": "JSESSIONID=0387B9D1BF9FA658D095713B75976EF8",
        "x-voltmx-authorization": "eyAidHlwIjogImp3dCIsICJhbGciOiAiUlMyNTYiIH0.eyAiX2VtYWlsIjogInBhdWxzdGVwaGVuLndpdGhlcnNAaGNsLmNvbSIsICJfdmVyIjogInYxLjEiLCAiaXNzIjogImh0dHA6Ly9sb2NhbGhvc3Q6ODA4MC9hdXRoU2VydmljZS9hY2NvdW50cyIsICJfc2NvcGUiOiAiZyIsICJfaXNzbWV0YSI6ICIvbWV0YWRhdGEvU053dmNOTy1ValJkSnFvQ0VYNW1NZz09IiwgIl9zZXNzaW9uX2lkIjogIjkwZWRkYzhjLWZjYzEtNGU4MC1iOTU2LTdiNGVhMTI2ZGQwZiIsICJfcHVpZCI6IDQ1MTYxOTQ4ODAxNzYsICJfaWRwIjogInVzZXJzdG9yZSIsICJleHAiOiAxNzExNDU2MTMxLCAiaWF0IjogMTcxMTQ1MjUzMSwgIl9zZXNzaW9uX3RpZCI6ICJhY2NvdW50cyIsICJfcHJvdl91c2VyaWQiOiAicGF1bHN0ZXBoZW4ud2l0aGVyc0BoY2wuY29tIiwgImp0aSI6ICJiMzE2OTdkYS00YjgwLTQxZDQtOWQ2Yi00MTY4YWIwNjRjMWUiLCAiX2FjcyI6ICJhY2NvdW50cyIgfQ.aZrLnTvl8noUTb_K7ulpNpYOADmx-CkecDH0C24vE-P9ZxiWQmyShdeto-RSu8rBlh5gzDNHqw2PwXcjXgByFLImroBpy7chbifHCWr5pBicBneCCcZWLE-6sVewTjwWQd__noNhYftki2dAwtv5oEx3d87NYV_RGikGpjkQk8c9MZpmPQAb3up2-hGSROAAlhmHwM3hRB7avofUMwMpWVDt0peYeTxr51qVIYjoG0U8i0-eb4Xg9ZaT1VgVEY4H5Yb-W_qdsxlJdk70pIZlQH_HiydwRSqqUe7AGEo6Tr45oeexTxbXiARV9p-dB4VlS0RSQp_wDvKsXFaLkoXuYA",
        "host": "localhost:8080",
        "connection": "Keep-Alive",
        "accept-encoding": "gzip,deflate",
        "x-voltmx-server-console": "ADMIN-PORTAL-LOGICAL-URL-CHANGE",
        "user-agent": "Apache-HttpClient/4.5.13 (Java/11.0.13)"
    },
    "params": {
        "current_serviceID": "helloWorld",
        "current_appID": "foundry-lab-vs",
        "appID": "foundry-lab-vs",
        "eventObserverID": "helloWorld",
        "curent_apiVersion": "1.0",
        "serviceID": "helloWorld",
        "vsTestingContext": "true"
    }
    },
    "response": {},
    "session": {
    "attributes": {
        "KCookie": []
    },
    "cookies": {}
    },
    "serviceInputParams": {}
}|
End Function

  2. Replace data = ctx.Context with data = getMockData().

  3. Run the script.

Success

The code should print out the following JSON:

{"debugMessages":[],"errorMessage":"","headerParams":{},"inputParams":{},"requestParams":{},"result":{"message":"Hello World!"},"session":{}}