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

Also Research Cloud plugins 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: plugins of the application 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 application offering.

  2. Plugins 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 Plugin 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 plugin

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

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

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

Then, fill in the dialog for the plugin'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 plugin. 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 an application 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 application. If the application 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 plugin's Ansible Playbook

Now that the plugin has the desired parameter, you can refer to it in the plugin'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 plugin's Powershell script

For a Powershell script plugin 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:


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 other catalog objects. Not just in plugins.

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

So when specifying parameters in applications or application offerings, the Research Cloud portal will help you to get insight in which parameters exist in the involved plugins and in the deployment script. The portal also indicates, whether the available parameters can be overridden and whether they are required.

When adding a parameter in an application, you can choose the key from a drop-down list:

The drop-down list shows you the keys of all the ovewritable parameters of the current plugins of the application:

Additionally, you are notified which parameter in which plugin will be overwritten:

Parameters in application offerings have the same support for choosing a key. Here the possible keys of the application, the plugins and the subscription are shown.

Override hierarchy

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

The path for resolving plugin parameters looks like this:

plugin < application < application offering < 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 plugin on the far left being the destination.

For the deployment script parameters the path is this:

deployment script < subscription < flavour < application-plugins < application < application offering < workspace-user (see below)

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

Again: all instances other than plugins 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.

Workspace-user input: interactive parameters

Sometimes it is desirable to have the user who starts a workspace fill in a value for a parameter.

This can be achieved by adding a parameter to the application offering.

This added parameter should override the parameter of a plugin or of the deployment script. It also overrides all other overrides that might be placed in the hierarchy levels in between.

Obviously, this is only possible for parameters that are actually overwritable.

With the overriding parameter in the application offering in place, the end user will be prompted to fill in the required value.

That is, just before the workspace is actually created.