Workspace Launch Forms

The Kasm Workspaces platform, allows administrators and systems integrators the ability to present custom forms to end users when they launch a Workspaces session. The Launch Config property defined on the Workspace entry is the schema for the form to present to the user. Once defined, when a user chooses that Workspace from the launcher, the custom form will be rendered to the user to gather the input.

The results of the configuration will be placed inside the Workspace session at a defined location. The administrator then can create startup scripts for that Workspaces that can process the information.

This feature is available on Container based Workspaces and Server/Server Pool Workspaces if the Kasm Windows Service is installed.

Quick Example

The administrator defines the Launch Config on the Workspace

../_images/launch_config_example_config-1.png — **Launch Config JSON Entry**

The Launch Config form presented to the user.

../_images/launch_config_example_dash-1.png — **Launch Config Form**

Per the file_mapping section of the Launch Config a file is written to disk at /tmp/launch_selections.json within the session with the key/value pair of the user’s selections.

../_images/launch_config_example_file-1.png — **Launch Selections File**

The administrator configures a startup scirpt for the session to parse the user’s selections from the file and do something within them. In this example, the command line tool jq is used to collect the desired value from the selections file
Startup Script Snippet
```
    #!/usr/bin/env bash
    set -ex
    
    TAILSCALE_KEY="$(jq -r '.tailscale_key' /tmp/launch_selections.json)"
    tailscaled &
    tailscale up --authkey=${TAILSCALE_KEY}
```

Launch Config Schema

The Launch Config JSON schema requires two top level keys:

file_mapping: Describes where the user’s form selections will be writted to disk. This ultimately leverages the File Mapping feature under the hood.
launch_form: Describes the form elements that should be presented to the user.

file_mapping

An object describing where the json file should be written within the Workspace session that contains the user’s form selections.

{
  "file_mapping": {
    "destination": "/tmp/launch_selections.json",
    "is_readable": true,
    "is_writeable": false,
    "is_executable": false
  }
}

Properties

destination* string: The file path where the user’s launch selections should be written. This will be a json formatted file. Since this feature leverages File Mapping, Windows Sessions can leverage special environment variables when defining the path.
is_readable bool: if true (default) the file will be readable.
is_writeable bool: If false (default) the file will be mounted as a read-only filesystem
is_executable bool: if false (default) the file will not be marked as executable.

launch_form

An array of objects (order implied) that describes individual form elements that should be presented to the users. This schema supports defining multiple element types, conditions on when to display certain elements, and input validation options.

{
  "launch_form": [
    {
      "key": "vpn_service",
      "label": "VPN Service",
      "value": null,
      "allow_saving": true,
      "required": true,
      "placeholder": null,
      "help": "This is the vpn service",
      "input_type": "select",
      "options": [
        {
          "value": "tailscale",
          "label": "TailScale"
        },
        {
          "value": "openvpn",
          "label": "OpenVPN"
        }
      ],
      "validator_regex": null,
      "validator_regex_description": null,
      "display_if": null
    },
    {
      "key": "tailscale_key",
      "label": "Tailscale Auth Key",
      "allow_saving": true,
      "value": null,
      "placeholder": "Auth Key",
      "required": false,
      "help": "The Auth key for tailscale",
      "input_type": "text",
      "options": [],
      "validator_regex": "[\\w\\-]{0,30}",
      "validator_regex_description": "Alphanumeric, including underscores and hyphens, Max 30 characters.",
      "display_if": [
        {
          "key": "vpn_service",
          "value_regex": "tailscale"
        }
      ]
    }
  ]
}

../_images/multi-stage-example.png — **Launch Selections File**

Properties

key* string: A unique name for the item. This value is not user facing. The key will be the same key used in the selection output.
label* string: A user-facing name for the item.
value* string: The default value to assign for the item. null should be used if no default is to be defined.
allow_saving* bool: When enabled, the end user will be presented the option to cache the selections for this item in their browser, so that they are remembered and pre-populated the next time the form is presented. The default is false.
placeholder* string: Placeholder text that is used inside the form element. This may be a hint to the user for the type of input expected.
required* bool: If true, this item must be filled in by the user before submission is allowed
help* string: This string will be displayed as a subtitle for the menu item. A short description of the item may be helpful for the end user
input_type* string: The type of input for this item. Acceptable value are text, select, password, number, textarea, passwordtextarea, email
options* array of objects: Used for select input_types. The array of objects (order implied) should each container a value and label key for the dropdown options to present to the user. If not applicable set this value as an empty array []
validator_regex* string: A regular express to be used to validate the user’s entry. Since this regex is embedded in JSON , quotes and slashes bust be escaped.
validator_regex_description* string: A description to present to the user if the input does not pass the regular expression validator. It should instruct the user what entries are valid.
display_if* array of objects: An array of objects that determines when to display this item. Each object should contain a key which should match the key for another item in this structure, and value_regex which runs a test against the value of the referenced key. If any of the conditions in this array matches, this item will be displayed to the user. Set this entry to null if not applicable