User Form¶

The configuration file form.yml is responsible for:

defining all the attributes used throughout the various ERB files (defined as the session context) that make up the Interactive App
setting the HTML form input or hard-coded value of each attribute
designating a cluster to submit the batch job to

It is located in the root of the application directory.

Assuming we already have a sandbox Interactive App deployed under:

${HOME}/ondemand/dev/my_app

The form.yml configuration file can be found at:

${HOME}/ondemand/dev/my_app/form.yml

Then in the browser, navigate to the Dashboard App and choose in the top right menu: Develop → My Sandbox Apps (Development). Finally click Launch My App from the list of sandbox apps.

You should now see the HTML form used to gather the user-defined attributes for building and launching the my_app Interactive App session.

Tip

You can include dynamically generated content in the form by renaming the form file to form.yml.erb and incorporating ERB syntax.

Configuration¶

cluster (Array<String> or String)

the cluster ids that the Interactive App session is submitted to.

Note

Prior to 1.8, this configuration was a single string (a single cluster). We now support one application submitting to multiple clusters. See the section below on configuring which cluster to submit to for more information.

Warning

The cluster id must correspond to a cluster configuration file located under:

/etc/ood/config/clusters.d

form (Array<String>): a list of all the attributes that will be used as the context for describing an Interactive App session

Note

The attributes that appear as HTML form elements will appear to the user in the order they are listed in this configuration option.

attributes (Hash): the object defining the hard-coded value or HTML form element used for the various custom attributes

cacheable (Boolean): whether or not the application is cacheable or not. Defaults to true.

Attributes¶

Attributes are variables whose values can be set either by the user from within an HTML form or hard-coded to a specific value in the form configuration. These attributes and their corresponding values are then made available to the Interactive App through its intermediate steps: Render Template and Job Submission.

Predefined Attributes¶

The Dashboard that supports these plugins provides the plugins with some useful predefined attributes that can be included in the form: configuration list with very little or no modification on the part of the developer.

So a very simple form.yml that requests the user input a queue followed by an account to submit the batch job (interactive session) to, and then subsequently submits the job to that queue without any customization on the part of the app developer can look like:

# ${HOME}/ondemand/dev/my_app/form.yml
---
cluster: "owens"
form:
  - bc_queue
  - bc_account

The most commonly used predefined attributes are given as:

bc_account

This adds a text_field to the HTML form that will be used as the charged account for the submitted job.

This attribute gets directly set on OodCore::Job::Script#accounting_id.

bc_queue

This adds a text_field to the HTML form that will supply the name of the queue that the batch job is submitted to.

This attribute gets directly set on OodCore::Job::Script#queue_name.

bc_num_hours

This adds a number_field to the HTML form that describes the maximum amount of hours the submitted batch job may run.

This attribute gets converted to seconds and then set on OodCore::Job::Script#wall_time.

bc_num_slots

This adds a number_field to the HTML form that describes the number of processors, CPUs on a single node, or nodes that the submitted job may use (depends on the resource manager used, e.g., Torque, Slurm, …).

This attribute manipulates the brittle OodCore::Job::Script#native field with a value that depends on the given resource manager for the cluster.

Warning

This predefined attribute is very resource manager specific, and is the most brittle of all the other predefined attributes. May require customization (see Customizing Attributes) to work at your center.

bc_email_on_started

This adds a check_box to the HTML form that determines whether the user should be notified by email when the batch job starts.

This attribute sets value of OodCore::Job::Script#email_on_started depending on whether the user checked the box or not.

Customizing Attributes¶

For each defined attribute in the form: configuration option, you can modify/override any component that makes up the HTML form element in the attributes: configuration option, e.g.:

attributes:
  my_custom_attribute:
    label: "My custom label"
    ...

The available configuration options that can be modified for a given attribute are:

widget (String, null)

the type of HTML form element to use for input

text_field
text_area
number_field - can use min, max, step
check_box
select - can use options
hidden_field
resolution_field (used for specifying resolution dimensions necessary for VNC)

Some other fields that have varying support across different browsers include: range_field, date_field, search_field, email_field, telephone_field, url_field, password_field.

Default

Accepts any text

widget: "text_field"

Example

Accepts only numbers

widget: "number_field"

value (String, null)

the default value used for the input field

Default

None

value: ""

Example

Set default value of 5

value: "5"

Warning

Values get cached so that users do not need to repeat previous session submissions. So this default value will only appear for the user if they have no cached value.

label (String, null)

the label displayed above the input field

Default

Uses the name of the attribute

Example

Better describe the attribute

label: "Number of nodes"

required (Boolean, null)

whether this field must be filled out before submitting the form

Default

Not required by default

required: false

Example

Make field required

required: true

help (String, null)

help text that appears below the field (can be written in Markdown)

Default

No help text appears below input field

help: null

Example

Leave a long descriptive help message using Markdown

help: |
  Please fill in this field with **one** of the following
  options:

  - `red`
  - `blue`
  - `green`

pattern (String, null)

a regular expression that the control’s value is checked against (only applies to widgets: text_field, search_field, telephone_field, url_field, email_field, password_field)

Default

No pattern

pattern: null

Example

Only accept three letter country codes

pattern: "[A-Za-z]{3}"

min (Integer, null)

specifies minimum value for this item, which must not be greater than its maximum value (only applies to widget: number_field)

Default

No minimum value

min: null

Example

Set minimum value of 5

min: 5

max (Integer, null)

specifies maximum value for this item, which must not be less than its minimum value (only applies to widget: number_field)

Default

No maximum value

max: null

Example

Set maximum value of 15

max: 15

step (Integer, null)

works with min and max options to limit the increments at which a value can be set, it can be the string "any" or positive floating point number (only applies to widget: number_field)

Default

No step size

step: null

Example

Only accept integer values

step: 1

options (Array<Array<String>>, null)

a list of options for the select widget

Default

No options are supplied

options: []

Example

Provide a list of cars

options:
  - ["Volvo", "volvo"]
  - ["Ford", "ford"]
  - ["Toyota", "toyota"]

Note

Typically the options are given as a list of pairs. The first string in the pair is the option text and the second string in the pair is the option value.

The user will see a list of options “Volvo”, “Ford”, and “Toyota” to choose from in the HTML form, but the backend will process a value of either “volvo”, “ford”, or “toyota” depending on what the user chose.

cacheable (Boolean, true)

whether the form item is cacheable or not

Default

cacheable

cacheable: true

Example

The item is not cacheable

cacheable: false

Examples¶

The simplest example consists of only a cluster id

# ${HOME}/ondemand/dev/my_app/form.yml
---
cluster: "owens"

where we expect the Interactive App session to be submitted with the following cluster configuration file:

/etc/ood/config/clusters.d/owens.yml

After modifying the form.yml click Launch My App from the Dashboard sandbox app list and you should be presented with ONLY a Launch button, since we didn’t define form: or attributes:.

User-defined Attributes¶

The following configuration file

# ${HOME}/ondemand/dev/my_app/form.yml
---
cluster: "owens"
form:
  - my_module_version

defines a session context attribute called my_module_version.

After modifying the form.yml click Launch My App from the Dashboard sandbox app list and you will see an empty text box with the label “My Module Version”. The user can input any value here and launch the Interactive App session. This value will be made available to the batch job script and submission parameters that are discussed in a later section.

Hard-coded Attributes¶

The following configuration file

# ${HOME}/ondemand/dev/my_app/form.yml
---
cluster: "owens"
form:
  - my_module_version
attributes:
  my_module_version: "2.2.0"

does two things:

it defines a context attribute called my_module_version in the form: configuration option
it then sets the value of my_module_version to "2.2.0" in the attributes: configuration option to later be used when defining the batch job script and/or submission parameters

The user will now ONLY be presented with a Launch button in the HTML form because the attribute my_module_version is hard-coded, so there is no need for a input text box.

Customize User-defined Attributes¶

The following configuration file

# ${HOME}/ondemand/dev/my_app/form.yml
---
cluster: "owens"
form:
  - my_module_version
attributes:
  my_module_version:
    widget: "number_field"
    label: "Module version #"
    required: true
    help: "Please input a version number between 1-10"
    min: 1
    max: 11
    step: 1

does two things:

it defines a context attribute called my_module_version in the form: configuration option
it then describes the HTML form element to use for the my_module_version attribute

Caching form items¶

Since 1.8 caching form items is configurable. By default all form items are cacheable. As seen above you can enable or disable caching for the entire app when using the top level cacheable configuration. You can also configure on a per item basis through attributes.

Lastly you can also enable or disable this feature for the entire site, using the configuration OOD_BATCH_CONNECT_CACHE_ATTR_VALUES=false in the dashboard’s environment file /etc/ood/config/apps/dashboard/env.

Tip

Since you can configure caching at different levels the rule of thumb is the closer the configuration is to the form item, the higher the precedence.

Setting the configuration on the attribute overrides everything and setting it on a per app basis overrides the global setting.

Let’s see an example. Here, we’ve disabled caching for the app and did not set OOD_BATCH_CONNECT_CACHE_ATTR_VALUES, so the site-wide configuration is set to true by default. So, bc_num_slots and python_version are not cacheable, meaning the user will have to fill those form entries out every time they submit the job. But since bc_queue’s attribute is set to true, it is cacheable.

# ${HOME}/ondemand/dev/my_app/form.yml
# OOD_BATCH_CONNECT_CACHE_ATTR_VALUES is not set, so defaults to true
---
cluster: "owens"
cacheable: false
form:
  - bc_num_slots
  - python_version
  - bc_queue
attributes:
  bc_queue:
    cacheable: true

Configuring which cluster to submit to¶

In 1.8 there are now several ways to configure what cluster to submit to.

The easiest way is to use the the top level cluster configuration. If you’ve configured just one item, then the form UI does not change for the user. If you configure an array of two or more options then a select dropdown will automatically be added to the top of the form.

# ${HOME}/ondemand/dev/my_app/form.yml
# which will generate a dropdown select automatically
---
cluster:
  - "cluster1"
  - "cluster2"

Tip

GLOBs are also supported. So in the example above one entry of cluster* would have been equivalent to explicitly configuring both cluster1 and cluster2.

This means you could configure cluster: "*" to be able to submit to all clusters.

If you would prefer to use some other widget, or you wish to change the text being shown in the UI you can configure a cluster form item and specify it’s attributes. This gives you some flexibility in the form UI instead of the default select widget that shows all lowercase cluster names.

Here’s an example were the user will be shown a select dropdown menu item with different text than the default.

# ${HOME}/ondemand/dev/different_select_cluster/form.yml
---
form:
  - cluster
attributes:
  cluster:
    widget: "select"
    options:
      - ["cluster1", "The first cluster"]
      - ["cluster2", "The second cluster"]

The last option is to configure the cluster in the submit file. When using this option, there’s no need to add any cluster configuration to the form.yml.