Skip to content

Mapping of Workflow Parameters to UI

Jump to bottom
Chris Churas edited this page Sep 3, 2015 · 27 revisions

This page describes how to map Workflow Parameters to HTML Input fields. Each Workflow can have multiple Parameters.

WARNING: When annotating parameters in Kepler use all lowercase for parameter keywords ie: allowedworkspacefiletypes=foo..

  • NOTE: When rendering the workflow to the user also be sure to let the user set a name for their job. This value can be then used for the name field in the Job

Below is a Parameter extracted from a Workflow in JSON format.

{
    "type" : "text|textarea|checkbox|dropdown|file|hidden",
    "displayName" : "Text to display next to field for user",
    "help" : "Tooltip to display for user",
    "maxLength" : 0,
    "rows" : 0,
    "columns" : 0,
    "validationHelp" : "Text to display upon validation failure",
    "validationType" : "number|digits|string|email",
    "validationRegex" : null,
    "maxValue" : 0.0,
    "minValue" : 0.0,
    "nameValueDelimiter" : null,
    "lineDelimiter" : null,
    "isAdvanced" : false,
    "isRequired" : true,
    "maxFileSize" : 20000000,
    "valueMap" : null,
    "name" : "examplefileparam",
    "value" : "/somepath",
    "selected" : "Defines selected name for parameters of type dropdown",
    "allowedWorkspaceFileTypes" : null,
    "allowFailedWorkspaceFile" : false
  }

Description of each field

type

The type field defines the type of input the parameter requires.

{
    "type" : "text|textarea|checkbox|dropdown|number|file|hidden",
}

Currently supported types:

  • text is a html input control with attribute type set to text

  • textarea is a html textarea tag

  • checkbox is a html input control with attribute type set to checkbox If value set to true then the checkbox is checked and false if NOT checked.

  • dropdown is a html select tag

  • file is a html input control with attribute type set to file See File Parameter Type for more information.

  • hidden is a html input control with attribute type set to hidden These Parameters should NOT be displayed to the user, but passed on when creating the Job.

displayName

Text to display to user next to input field defined by type above.

{
"displayName" : "Text to display next to field for user",
}

help

Tooltip text to display to user via a mouse over or help icon that can provide information on how to set an appropriate value for the given Parameter

{
 "help" : "Tooltip to display for user",
}

maxLength

Defines maximum length in characters that are allowed for text parameter type

{
    "maxLength" : 25
}

rows

Defines number of rows to display for textarea parameter type

{
   "rows" : 4
}

columns

Defines number of columns to display for textarea parameter type

{
   "columns" : 50
}

validationHelp

Text to display upon validation failure.

{
   "validationHelp" : "Please enter a whole number between 1 and 10"
}

validationType

Defines the type of data expected for this parameter.

{
  "validationType" : "number|digits|string|email"
}

Currently supported types:

  • number Allow only floating point numbers or numbers with decimals (24.5, 12, -1234.23433). Can be limited by maxValue and minValue

  • digits Allow only digits that are wholenumbers ie (1,2,3,34,-1,-10). A (-) at the start is allowed to denote negative numbers. Can be limited by maxValue and minValue

  • string Allow ASCI characters. Can be limited by validationRegex

  • email Allow valid email addresses. Currently checked with this regular expression: ^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,64}$

nameValueDelimiter

Defines the delimiter used when parsing data from URL in value field for parameters of type dropdown. A suggested delimiter is ==

{
  "nameValueDelimiter" : "=="
}

isAdvanced

If set to true then this parameter should be displayed under an Advanced tab or denoted in such a way so the user understands this is parameter is for experts or those knowledgeable in the low level mechanics of the workflow.

{
  "isAdvanced" : "true"
}

name

Internal name for Parameter. This value matches the internal name of the Parameter in the Kepler workflow.

{
    "name" : "examplefileparam",
}

value

Default or initial value to set the field to when displaying to the user.

If the type is dropdown this value should be set to a web URL and will be fetched by the service when a single workflow is requested. Some services require authentication to be passed on and this service will detect and replace the following tags in the URL with values described:

@@userlogin@@ -- Any instances of this in URL will be replaced with the userlogin query parameter value

@@usertoken@@ -- Any instances of this in URL will be replaced with the usertoken query parameter value

@@user@@ -- Any instances of this in URL will be replaced with the runasuser query parameter value

{
    "value" : "/somepath"
}

selected

Defines selected value for parameters of type dropdown This value is the value displayed to the user from the valuemap or what is known as the name in the name=>value map

{
   "selected" : "red"
}

allowedWorkspaceFileTypes

Defines a comma delimited list of valid WorkspaceFile types valid for the associated Parameter. The UI should only let the user select WorkspaceFiles that are in this list if set. The WorkspaceFile REST call supports a type field that will automatically restrict WorkspaceFiles.

{
   "allowedWorkspaceFileTypes": "NCMIR Data Import,CHM image dataset"
}

allowFailedWorkspaceFile

If set to true then WorkspaceFiles that have their failed field set to false are allowed as input for the given parameter. Otherwise this value is assumed to be false. The UI should only let the user select WorkspaceFiles that match this criteria. The WorkspaceFile REST call supports a isfailed field that will automatically restrict WorkspaceFiles.

{
   "allowFailedWorkspaceFile": true
}

Examples

Text Parameter

JSON

{
    "type" : "text",
    "displayName" : "Some Text Parameter",
    "help" : "Tooltip to display for user",
    "maxLength" : 20,
    "validationHelp" : null,
    "validationType" : null,
    "validationRegex" : null,
    "maxValue" : 0.0,
    "minValue" : 0.0,
    "nameValueDelimiter" : null,
    "lineDelimiter" : null,
    "isAdvanced" : false,
    "isRequired" : true,
    "maxFileSize" : 0,
    "valueMap" : null,
    "name" : "yikes",
    "value" : "hi"
  }

HTML

Some Text Parameter: <input type="text" value="hi" name="yikes">

HTML UI

HTML UI Text Field

Textarea Parameter

JSON

{
    "type" : "textarea",
    "displayName" : "Some Textarea Parameter",
    "help" : "Tooltip to display for user",
    "maxLength" : 20,
    "rows" : 2,
    "columns" : 10,
    "validationHelp" : null,
    "validationType" : null,
    "validationRegex" : null,
    "maxValue" : 0.0,
    "minValue" : 0.0,
    "nameValueDelimiter" : null,
    "lineDelimiter" : null,
    "isAdvanced" : false,
    "isRequired" : true,
    "maxFileSize" : 0,
    "valueMap" : null,
    "name" : "yikes",
    "value" : "hi"
  }

HTML

Some Textarea Parameter: <textarea> rows="2" cols="10">hi</textarea>

HTML UI

HTML UI Textarea Field

File Parameter

Hidden Parameter

JSON

{
    "type" : "hidden",
    "displayName" : "Can be anything cause its not displayed to user",
    "help" : null,
    "maxLength" : 0,
    "validationHelp" : null,
    "validationType" : null,
    "validationRegex" : null,
    "maxValue" : 0.0,
    "minValue" : 0.0,
    "nameValueDelimiter" : null,
    "lineDelimiter" : null,
    "isAdvanced" : false,
    "isRequired" : true,
    "maxFileSize" : 0,
    "valueMap" : null,
    "name" : "yikes",
    "value" : "hi"
  }

HTML

Some Text Parameter: <input type="hidden" value="hi" name="yikes">
Clone this wiki locally