Child pages
  • Elements of a Tool
Skip to end of metadata
Go to start of metadata

This page lists the elements which make up a tool.  These are components of the tool definition, controlling what the tool will do and the resources it will use when it runs.

The elements of a Tool are contained within 4 sections of the screen (each section is described below, along with the elements contained within them) :-

Where an element is marked with an (M), it means that this element is mandatory when defining a tool.

It is advised to consult with your system administrator when defining a tool to ensure resource definitions are appropriate.

Header Section

The Header Section contains the top level information about a tool, e.g. its name, help text and type.

These are contained in the screen as illustrated below:-

Tool Name (M)

This is a string value and will be the name of the tool as shown in the ERWB Run Tool Dashlet (Select Tool) when it is run.  This can be up to 255 characters.

Tool Help (M)

This is the text that is shown when a user clicks the ? icon next to the selected tool in the ERWB Run Tool Dashlet.  This can contain text and html mark-up, including <a href=" content to embed links to other sources of help.

Tool Type (M)

This is the type of tool that you want to create, the options are as follows :-

TypeDescription
Batch - One OffA batch tool which the user executes once, producing a single set of results. This type is also used where the tool is to be defined using multiple Roles and VMs.
Batch - Simple RepeatA batch tool which is run multiple times using the same input and parameters
Batch - Multiple Step RepeatA batch tool which is run many times, passing a set of numeric values as a parameter into each tool run (min, max and step)

Batch - Multiple Random Sweep

A batch tool which is run many times, passing a random numeric value (within a min and max) as a parameter into each tool run
Batch - Driving DataA batch tool which is run many times, reading in a set of parameter values from a file into each tool run
Interactive - WebAn interactive tool connected to via a browser
Interactive - X11An interactive tool connected to via X11 connection

Back to Top

TEMPLATE SECTION

This section defines technical aspects of the tool definition, base connection to vCloud resources and the template upon which the tool will is based.

Keep After Finish

This controls whether a tool stays running after is has completed or not.  For Batch tools, this should be set to No (un-checked), for Interactive tools this should be set to Yes (checked).   A Batch tool can be set to Yes, e.g. to stay running when complete, although the resulting tool run would need to be stopped manually by the user.

VApp Template (M)

This lists the available templates upon which your tool can be built.  These are made available via vCloud.  You must select a template, which will then populate the VMs SECTION (below) with the associated settings.

Note: if you require an additional template (or cannot see the template you need) you need to contact your System Administrator to arrange making the required template available to the ERW.

TEMPLATE ADVANCED OPTIONS (these elements can be optionally displayed, usually where more technical tool definition is required)

VApp  URL (M)

This is the entry point to the JASMIN infrastructure.  It is very unlikely that this would be changed.

VApp User (M)

The VMWare User (@ tenancy name) account name which enables access to the use of the JASMIN VDC resources.  This is only changed if the ERW is deployed into a new VDC.

VApp Password (M)

The VMWare User Password which enables access to the use of the JASMIN VDC resources. This is only changed if the ERW is deployed into a new VDC.

VCloud Data Centre

The name of the JASMIN VDC.  This is only changed if the ERW is deployed into a new VDC

VCloud Network

The network range used within the constructed VMs.  It is very unlikely that this would be changed.

Back to Top  

ROLES SECTION

This section defines the instructions that will be performed as part of the tool run, in the form of a script, including script commands which may embed parameters (which are offered to the user as part of a tool run).  For Interactive tools, this section also defines connection details and commands.

Role Script (M)

This is the script (set of commands) that will be performed when the tool is run.

As a default, the script contains #!/bin/sh to begin a shell script and mkdir /home/$$username/output to ensure that the output folder is created into which tool run results can be stored.  (It is from this location that results will be returned back to the ERW after a tool run - See Output Path below)

If commands need to embed a parameter value, the value of the parameter Anchor (see below) should be used within the command, e.g. Rscript MM_Probability_Occurance.r $species $factor ($species and $factor are the parameter anchors)

Where a tool is of type Batch - Multiple Step Repeat, Batch - Multiple Random Sweep, or Batch - Driving Data, reference to the passed in parameter value (i.e. the numeric value or the driven data value) is $$currentValue

PARAMETERS

Parameters are defined as follows:-

Label

This is a string value which is presented as the parameter label to the user when the run the tool, i.e. the label to the left of the input field (see ERWB Run Tool Dashlet).   This is a text string, usually with a ':' character on the end.

Parameter Type

The parameter type can be either Text or Select.

Text parameters will take in the parameter value as a string, presented to the user as a field to complete as part of the tool run.

Select parameters will take the value as defined in its set of Values (see below) from a drop-down presented to the user for selection as part of the tool run.

Anchor

This is the value that will be used as the reference to the parameter by commands within the Role Script.  This is a string value which must be prefixed with a '$' character.  The parameter value supplied during the tool run will replace the anchor at run time.

Tooltip

This is the text that is shown when a user clicks the ? icon next to the parameter in the ERWB Run Tool Dashlet.  This can contain text and html mark-up, including <a href=" content to embed links to other sources of help.

Values

This is used for a Select parameter to define the values for the parameter and the associated labels presented to the user.  

The values are entered in pairs using the structure value|label where value is the actual value which will be passed into the script command and the label is the string value displayed to the user for selection, separated with a '|' (pipe) character.  Each entry in the list should be separated by a carriage return. e.g.

ph|soil pH                 -  (ph is the value, soil pH is the label)
fert|substrate fertility
wet|soil moisture

In the above example, the values soil pH, substrate fertility and soil moisture will be presented in a drop-down for selection by the user when the tool is run.

Example Parameters

Examples for the entry of parameters and how they will look within the ERW Tool Run dashlet are as follows:-

An example of Text parameter:-

Tool Definition

As shown on Tool Run Dashlet

An example of Select parameter:-

Tool Definition

As shown on Tool Run Dashlet

Output Path (M)

This defined where any output from the use of the tool will be expected to be before it is copied back to the ERW when the tool has finished.  The default is /home/$$username/output which means that the output of the tool is expected to be placed into a folder called output within the user's home folder.

This can be changed as part of tool definition, as long at the tool is designed to place the output into the specified location.

Protocol (Interactive - Web tools only)

This is either http or https, depending on the protocol of your Interactive - Web tool

Port (Interactive - Web tools only)

This is the port through which your Interactive - Web tool will be connected

Path (Interactive - Web / X11 tools only)

This is the command line application to run for your interactive tool. E.g. qgis


ROLE ADVANCED OPTIONS (these elements can be optionally displayed, usually where more technical tool definition is required)

Role Name

The is the name of the role given on creation.  It can be changed if needed.

The Role Name is used to associate the role to a VM (in the VMs Section below)

Back to Top  

VMs SECTION

This section defines the resource settings for the VMs in the tool, defines the O/S guest customisation and associates the role to the VM.

Role (M)

This is a dropdown of the available roles defined in the ROLES SECTION.  This associates the role (and the Role Script/connection details) to the VM.

VM CPUs / VM Cores

This is the number of CPUs and Cores (per socket) that will be allocated to the VM when the tool is started.  These will default to either the setting from the selected template or the loaded tool.  See below for valid CPU/Core settings.

The number of CPUs must divide equally into the number of Cores.  (e.g. 8 CPUs requires 1,2,4 or 8 Cores, 6 CPUs requires 1,2,3 or 6 Cores, 7 CPUs requires 1 or 7 Cores).

VM Memory (GB)

This the amount of RAM (in GB) that will be allocated to the VM when the tool is started.  This will default to either the setting from the selected template or the loaded tool.  Select either 1,2,4,8,16,or 32 from the drop-down.

VM Disk (GB) (M)

This the amount of Disk Space (in GB) that will be allocated to the VM when the tool is started.  This will default to either the setting from the selected template or the loaded tool.  E.g. 20 equals 20 GB.  (only type the number into the field)

VM ADVANCED OPTIONS (these elements can be optionally displayed, usually where more technical tool definition is required)

Start Order (M)

This defines the start order of the VM if the tool is to contain multiple VMs as part of its definition.  The lower the number, the earlier the VM will start in relation to the other VMs.

VM Name (M)

The name of the VM when created as part of a tool run.  This is mainly used to distinguish between output from a tool which has made up of multiple VMs. 

Guest Customisation (M)

This section contains the VM O/S customisation script that will be executed when the VM starts up as part of the tool run.

The default script carries out the necessary O/S Guest Customisation to provide access to the resource by the ERW user.

This is where any specific customisation of the O/S can be orchestrated, e.g. to install packages required by the tool or to enable a tool to work with CMIS Sync.

The default script is designed to work with the CentOS 6.5 base operating system, so if your tool is based on a different O/S you must change this script accordingly.

Back to Top  

 

 

 

 

 

 

 

  • No labels

2 Comments

  1. Introduction needed at the start of the page to the different sections.

     

    Define also Templates, Roles and VMs.

     

    Give instruction that the user should consult with their administrator when doing these things!

  2. Anonymous

    "set to No (un-ticked)"  I think you used the American (un)checked when this was documented on another page.

    Advanced options: Would everyone expect to see these details, or is this just your example?  Where do these come from?  Does it depend on which kind of user you are as to whether you care or need to care?  And can you change the template once created?  This implies you can.

    Screenshots here are different since they are full size so the page has to be scrolled to the right to see it all.

    Show examples of text and select parameters (how they're entered and how they're displayed at run time).

    This page answers some of my comments from other page(s).  Sensible page order and hyperlinks or tooltips on other pages ought to help cross-refer.

    "qgis" is usually all uppercase (QGIS).

    "... as part of it's definition" has no apostrophe in "its".

     

    Barbara