Skip to content

Parameter Specification

A parameter is represented by a JSON object which defines the parameter's properties. Parameters are typically defined together as a list within a Form.

Key Type Required Default Description UPM/TD
name str ✔1 ➖ The unique identifier for the parameter. ✔
type enum ✔ ➖ The parameter type. ✔2
valueType enum: string,
stringEncoded,
stringEncodedParts3		 ✔ ➖ Specifies how the parameter value is stored. stringEncoded will use FMEParsableText encoding to escape special characters. ❌
defaultValue any ❌ ➖ The default value of the parameter. ✔
prompt str ✔/❌4 ➖ A human-readable prompt for the parameter. ✔
showPrompt bool ❌ true/false Specifies whether the parameter prompt is visible. Default value varies based on parameter type.5 ✔
supportedValueTypes array(enum):
expression,
globalParameter,
null,
noOp,
none		 ❌ ["globalParameter"] A list of value setting methods to allow. "expression" includes attribute values. "literal" is not included in the enumeration as literal values are always allowed. To exclude all value types except literals, specify ["none"]. ➖6
required bool ❌ true If true, the parameter will be highlighted as invalid when empty. ✔
setValue str,
dyanamic		 ❌ ➖ Dynamic property that updates the parameter value. Default is not to modify value. ❌
visibility enum,
bool,
dyanamic		 ❌ visibleEnabled Dynamic property that controls the visibility and enabledness of the parameter. ➖7
expressionSettings obj ❌ ➖ An object containing settings related to defining an expression value type.
Only relevant when supportedValueTypes contains expression.		 ❌
choiceSettings obj ✔/❌8 ➖ An object containing settings related to defining the choice options the parameter will display. Behavior depends on parameter type.8 ✔

Deprecated

Key Type Required Default Description
hidden bool ❌ false If true, parameter will not be shown in the ui, but its value will be stored. (Replaced by visibility.)
deprecatedFlags array(enum):
wholeline,
showZipButton,
noEdit,
disabledOnly,
alwaysEnabled,
forceDefs,
ignoreValue		 ❌ ➖ Allows specifying a list of legacy flags.
Note: these settings should be avoided at all costs in new parameters.

expressionSettings

Key Type Required Default Description UPM/TD
sourcePorts arr(str) ❌ [] A list of input port names to include attributes from.
If empty, attributes from all input ports will be included.		 ❌
supportsConditionals bool ❌ true Enables the conditional value editor. ❌
supportsAbort bool ❌ false Enables the "Stop Translation" option in the conditional value editor. ❌
subsequentFeatures int
[-1, 100]		 ❌ 0 Number of subsequent adjacent features to display attribute references for.
If -1 is specified, the maximum number is used.		 ❌
priorFeatures int
[-1, 100]		 ❌ 0 Number of prior adjacent features to display attribute references for.
If -1 is specified, the maximum number is used.		 ❌

choiceSettings

Key Type Required Default Description UPM/TD
choiceSet enum ✔ userDefined Specifies a predefined set of choices to use for the parameter. ➖9
include arr(str) ❌ ➖ A list of values to intersect with the choices defined by the choiceSet.
Mutually exclusive with the exclude key.		 ❌
exclude arr(str) ❌ ➖ A list of values to exclude from the choices defined by the choiceSet.
Mutually exclusive with the include key.		 ❌
sort enum:
noSort,
naturalSort		 ❌ various10 Controls how to sort the choice list. ✔
choices arr(obj) ❌ ➖ A list of objects for manually specifying choice values. ✔

choices

Key Type Required Default Description UPM/TD
value str ✔ ➖ The value of the choice to be used in the backend. ✔
display str ❌ ➖11 The string to display to the user, subject to translation12. ✔
icon path ❌ ➖ A file path to an image file to use as an icon, shown as part of the choice. ❌
textFormatting obj ❌ ➖ An object for specifying formatting options to apply to the choice. ❌
textFormatting
Key Type Required Default Description UPM/TD
bold bool ❌ false If true, the display text will be bold. ❌
italic bool ❌ false If true, the display text will be italicized. ❌
strikeout bool ❌ false If true, the display text will be stricken out. ❌
underline bool ❌ false If true, the display text will be underlined. ❌

Types

  • checkbox - Make a boolean choice.
  • color - Select a color value.
  • datetime - Select a date.
  • dropdown - Select a single item from a dropdown menu.
  • file - Select a file or folder on the local file system.
  • font - Select a font and additional properties.
  • geometry - Create a geometry object.
  • group - A container for multiple parameters arranged sequentially.
  • icon - Select from a set of icons.
  • listbox - Select items from a list.
  • message - Display static text.
  • multi - Deprecated.
  • number - Specify integer or float values.
  • password - Input a password.
  • radio - Select one of several toggle buttons.
  • range - Select a range of numbers.
  • table - A table with cells composed of other parameter types.
  • text - Enter text.
  • tree - Select items from a tree.

Choice Sets

Dynamic Properties

For dynamic property object syntax, see dynamicproperties

visibility

Value Description
visibleEnabled The parameter will be enabled and visible in the UI, unless its parent parameter (a group or table) is disabled and/or hidden.
visibleDisabled The parameter will visible, but disabled.13
hiddenEnabled The parameter will hidden from the UI but be treated as enabled internally.
hiddenDisabled The parameter will hidden from the UI and disabled.
true Synonym for visibleEnabled.
false Synonym for hiddenEnabled.
other value or undefined Default to visibleEnabled.

visibility Example:

{
  "visibility": {
    "if": [
      {
        "$hasValue": {
          "parameter": "OFF_BUTTON",
          "value": "OFF"
        },
        "then": "visibleDisabled"
      }
    ]
  }
}

setValue

Type Description
str The parameter value will be set to this string value.
obj The parameter value will be set to object "value", but subject to extra conditions.
other types or undefined The parameter value will not be modified

"value" Object

Key Type Required Default Description UPM/TD
value str ✔ ➖ The value to set the parameter to. ❌
override bool ❌ true Specifies whether to override user-provided values. ❌
evaluateOnLoad bool ❌ false Specifies whether value should be set when loading the form.14
⚠ Warning: this will overwrite previously saved values.		 ❌
value string Example:
{
  "value": {
    "if": [
      {
        "$hasValue": {
          "parameter": "X_MAKES_OTHER_Y",
          "value": "X"
        },
        "then": "Y"
      }
    ]
  }
}

In the above example, if "X_MAKES_OTHER_Y" has value "X", then the parameter value will be unconditionally set to "Y".

value object Example:
{
  "value": {
    "if": [
      {
        "$hasValue": {
          "parameter": "IF_X_THEN_SET_TO_Y_BUT_DONT_OVERRIDE",
          "value": "X"
        },
        "then": {
          "value": "Y",
          "override": false
        }
      }
    ]
  }
}

In the above example, if "IF_X_THEN_SET_TO_Y_BUT_DONT_OVERRIDE" has value "X", then the parameter value will be set to "Y" if the user has not input a value for the parameter.

Example

{
  "parameters": [
    {
      "name": "MESSAGE",
      "type": "text",
      "valueType": "stringEncoded",
      "supportedValueTypes": [
        "expression",
        "globalParameter",
        "conditional"
      ],
      "prompt": "Log Message",
      "required": true,
      "defaultValue": "Feature is:"
    },
    {
      "name": "MAXCOORDS",
      "type": "number",
      "valueType": "string",
      "supportedValueTypes": [
        "expression",
        "globalParameter",
        "conditional"
      ],
      "prompt": "Max Coordinates Per Feature",
      "required": true,
      "defaultValue": 20
    },
    {
      "name": "MAXFEATS",
      "type": "number",
      "valueType": "string",
      "supportedValueTypes": [
        "expression",
        "globalParameter",
        "conditional"
      ],
      "prompt": "Max Features to Log",
      "required": true,
      "defaultValue": 20
    },
    {
      "name": "FEATURE_TYPE",
      "type": "text",
      "valueType": "stringEncoded",
      "supportedValueTypes": [
        "expression",
        "globalParameter",
        "conditional"
      ],
      "prompt": "Feature Type Override",
      "required": false
    }
  ]
}

  1. Will be set to an auto-generated UUID if empty. ↩

  2. 🚧 Some types are currently unavailable: font, icon, radio, range ↩

  3. Internal Only: StringEncodedParts is for values that are lists where the list elements should be FMEParsableText encoded but not the list itself. This is used to avoid problems with list elements containing delimiter characters in their values. ↩

  4. Required when showPrompt is true. ↩

  5. As a general rule, parameters which span multiple lines (tables, groups, etc) do not show the prompt by default and are typically wrapped in a group with a title instead. ↩

  6. 🚧 Not all values/configurations are currently supported. ↩

  7. 🚧 Only conditional values are currently supported. ↩

  8. Required by the following parameter types: dropdown, listbox, radio, tree
    Optional for the following parameyer types: file, number, text
    Not supported by other parameter types. ↩↩

  9. 🚧 Some choiceSets are currently unavailable: encodings, exposableFormatAttributes, pointCloudComponents, pointCloudTypes readers, readerValues, writers ↩

  10. Default for user defined choice sets is naturalSort, and varies for predefined choice sets.
    For example, encodings are sorted by popularity, and attributeNames are sorted alphabetically. ↩

  11. If not specified, value of the value key will be displayed instead. ↩↩

  12. All display strings are subject to translation when enabled.
    To avoid translation, do not specify this key to display the untranslated value from the value key instead (see 11). ↩

  13. Disabled parameters appear grayed-out in the UI and have a value of <Unused> ↩

  14. Normally setValue conditions are only evaluated when a dependent parameter value changes, not when initially loading the form. ↩