Any more-than-trivial script has variables - "blanks" that have to be filled in to let the script fulfill its purpose.

Also Research Cloud components have a mechanism to provide values for variables. We refer to it with the term "parameters".


Two destinations for parameters

There are two sorts of scripts that contribute to the creation of a functioning workspace: components of the catalog item and the deployment script.

  1. The deployment script defines which OS a workspace is based on and how it is realized in a particular cloud. Deployment scripts are Terraform scripts. You implicitly choose a deployment script when you choose a subscription for your catalog item.

  2. Components are Ansible Playbooks that configure and enrich a workspace "from the inside" once the deployment script has created the workspace.

Both types of scripts can require particular values: variables that have to be provided to them. This requirement is expressed by adding a parameter to the script.

A developing user in Research Cloud can write a component that requires parameters.

(Deployment Scripts require parameters, too, but users cannot change deployment scripts, or write their own. As of now, passing values to deployment scripts seems to be too advanced a topic to address it, here. If you think that you have to do just that, please contact the servicedesk.)

Requiring a parameter in a component

When writing a component you can specify a parameter for its Ansible Playbook (or Powershell Script) like this.

You can do this in the third step of the component wizard.

Click on the "+" icon for adding a parameter.

Then, fill in the dialog for the component's new parameter:


Fill in the fields in the dialog:

  • Key: The name of a variable in your Ansible or Powershell script. This parameter will provide a value for the variable. All the parameters in a workspace are basically key-value pairs. So the choice of the key/variable name is of great technical importance. Make sure that it is unique within the workspace: prefix the key with the name of the component. That way, you make sure that the value only gets overridden intentionally. A more generic name like for instance "username" might get overridden, inadvertently.

  • Label: The text-label that is shown next to the value-field in a dialog. "Label" is only of use when the value for this parameter might be filled in by the workspace-user, interactively.

  • Description: Give an exact and concise description of what the effect of this parameter is. This text is also displayed to the workspace user when the value gets filled in interactively.

  • Source type: Most probably, you want to specify "Fixed", here. If you need to know more, you can also refer to the page Secrets and workspace info: special parameter source types.

  • Overwritable: Check this checkbox if you want  to allow a catalog item parameter of the same name to override the value. If the "overwritable" box is checked, you also get to specify the following two entries:
    • Initial value: This value will be used when no other instance overrides this parameter. This value is required, when the "Overwritable" flag is not set. Make sure that a specified value matches the "Data type" that you specify in this dialog.

    • Required: Check this checkbox if you want to be sure that a value will be specified by a parameter of the catalog item. If the catalog item does not give a value for this parameter, the parameter will be presented to the workspace-user to be filled in interactively.

Referencing a parameter in the component's Ansible Playbook

Now that the component has the desired parameter, you can refer to it in the component's Ansible Playbook.

Wherever in your Playbook you want to refer to a parameter, put the key of that parameter between quotes and double accolades like this:

"{{ MyParametersDemo-variable-A }}"

Note: always put quotes. They are not just for string types but they are part of the var-syntax in Ansible.

While talking about Ansible syntax anyway: the two values for a boolean parameter are true and false. Ansible is very tolerant when interpreting boolean values, but these two words in lowercase are also in line with the more generic yaml-syntax.

Referencing a parameter in the component's Powershell script

For a Powershell script component used for windows catalog items referencing a parameters is a bit different.

Wherever in your script you want to use the value of a parameter, your powershell script can read the value from an environment variable like this:

"[System.Environment]::GetEnvironmentVariable('MyParametersDemo-variable-A')"

Where 'MyParametersDemo-variable-A' is the key of the parameter.

The environment variable is only available for the special windows user that is used to configure the machine, it can't be used by other normal users without further steps.

Filling in or overriding a parameter value

Parameters can also be specified in catalog items. Not just in components.

The difference here is that it only makes sense to provide values for parameter-keys that are actually used by either one of the components or by the deployment script. These parameters are only about overriding or filling in other parameters downstream, not about requiring extra values.

When specifying parameters in catalog items, the Research Cloud portal will help you to get insight in which parameters exist in the involved components and in the deployment script. The portal also indicates, whether the available parameters can be overridden and whether they are required.

Override hierarchy

There are two paths along which parameters are resolved, when a workspace is created. One path ends at the components, the other path ends at the workspace's deployment script.

The path for resolving component parameters looks like this:

component < catalog item <  workspace-user (see below)

The order of the elements in this path means that each element can fill in or override a parameter's value of an element to its left, the component on the far left being the destination.

For the deployment script parameters the path is this:

deployment script < subscription < flavour < catalog item components < catalog item < workspace-user (see below)

Please note that any parameter that is *not* explicitly required either by the deployment script or by a component has no effect, there. These scripts would not "know" what to do with that value.

Again: all instances other than components and deployment scripts do not actually use the parameters, in any way. They may provide a value to a blank parameter or override an already existing value or, most of the time, they will just leave the parameters as they are.