FME Form: 2024.1

Creating and Modifying User Parameters

To create user parameters and manage existing ones, open the User Parameters dialog. From the Navigator, right-click on the User Parameters icon, and select Manage User Parameters. Alternatively, from the menu, select Tools > Manage User Parameters.

In the User Parameters dialog, the left pane lists all the existing user parameters for the workspace. (They are also listed in the User Parameters section of the Navigator.) You can click and drag on the parameters or use the toolbar icons to perform the following:

  • Change the order of the parameters at runtime. (You can also reorder the parameters in the Navigator by dragging them up or down.) Order is important because it affects when parameters are evaluated in the workspace. In particular, the value of one parameter may depend on another parameter that is evaluated earlier.
  • Remove a parameter.
  • Edit a parameter: Click on one to select it. The parameter's properties display on the right pane.
  • Add a parameter: Click the Insert icon (+) and select the type of user parameter you want to add (see Parameter Types, below). The parameter is added below the currently-selected parameter. In the right pane, configure the properties of the parameter according to its type (see Parameter Properties (Right Pane), below).
  • Arrange parameters in group boxes: Click the Insert icon and select Group Box. In the left pane, a group box is added below the currently-selected parameter. Click and drag other parameters into the group box as desired. In the right pane, configure the properties of the group box (you may need to re-select the group box to show its properties). See Parameter Properties (Right Pane), below.

When finished, click OK.

To view how the parameters display at runtime, click Preview.

Parameter Types

Parameter Type Creates a Parameter to...
Choice Choose one or more values.
Color Select a color value.
Datetime Enter a date and time. For information about output formats, see Standard FME Date and Time Format.
File/URL Choose the names and paths of existing files or folders, an output file or folder, or a URL.
Message Display a message at runtime.
Number Enter an integer or floating-point number. The number can be bounded or unbounded based on the specified Configuration.
Password Enter a password.
Text Enter a text string.
Yes/No Select or unselect a checkbox.
Attribute Name Choose names of feature type attributes, or items from a comma-delimited or space-delimited attribute list. Choices only populate in the context of a reference to the user parameter in the workspace, such as when the Attributes parameter of a StringReplacer transformer references an Attribute Name user parameter.
Coordinate System Choose a coordinate system.
Database Connection Choose a database connection.
Geometry Enter a geometry as a set of spatial coordinates in GeoJSON. When a workspace containing a Geometry published parameter is run from FME Flow, an interface is available for displaying the specified coordinates on a map and specifying the desired geometry. For more information, see Using the Geometry Parameter in FME Flow (previously FME Server).
Tip  To handle the JSON data returned by this parameter:
Use a GeometryReplacer transformer to turn the parameter value into a real geometry. Specify GeoJSON as the GeometryEncoding.
Use a JSONExtractor transformer to extract the coordinate values. For example, to extract X/Y coordinate values to a point feature, specify json["coordinates"][0] and json["coordinates"][1].
Reprojection File Choose a grid shift file for reprojecting data.
Web Connection Choose a web connection.
Advanced > Scripted Selection Access a callback method in a Python module that returns values available for selection and which may be obtained remotely, such as from a web service. Scripted selection parameters are useful in configuring *Connector transformers to access resources (for example, the Folder parameter of the GoogleDriveConnector transformer). For more information about using Python with scripted selection parameters, see the FME Packages SDK Guide.
Advanced > Scripted Value Access a Python script that assigns the value of a parameter to the workspace at runtime.

Parameter Properties (Right Pane)

A short, unique name for the parameter (or group box). This name is used to reference the parameter in values (for example, $(myIdentifier)) and menus.

The prompt for the parameter (or group box) that appears when you run the workspace.

Note  In some configurations, Prompt is not available; for example, when parameter type is Text and Display is Embedded Multiline Editor. As an alternative, place the parameter inside a group box, and set the group box Prompt as the parameter prompt.

If checked, the parameter is created as a published parameter. If unchecked, the parameter is created as a private parameter.

For more information, see Working with User Parameters.

If checked, the workspace does not run unless the user inputs a value. If unchecked, an input value is not required for this parameter.

Tip  Mouse over a parameter entry in the Navigator to discover if it is optional. Parameters include either [optional] or [required] in the tooltip.

This setting controls whether the end user can select an attribute to provide values to a parameter. If checked, the user cannot specify an attribute value for the value of the parameter. If unchecked, FME determines if the user can specify an attribute value for the value of the parameter, in addition to any values allowed by the parameter type. FME determines whether the parameter allows specifying an attribute value based on the parameter referencing the user parameter.

The parameters required in this field depend on the parameter type you choose.

You can populate the choices to display in a Dropdown, List, or Tree.

Tip  Limit Dropdown to a single selection from a small number of choices. To allow selecting from a large number of choices, use List, and check or uncheck Allow Multiple Selection accordingly.

If Tree is selected, specify a Tree Node Delimiter for the nodes of the tree. Then specify the Choices, using the delimiter to indicate under which node to place the value.

For example, this configuration uses a comma to delimit building choices by building site:

Mouse-over to view:

When the parameter is published, the choices appear like this:

Mouse-over to view:

Choice List Delimiter: If List or Tree is specified, you can choose the delimiter that separates multiple values as they are selected for display in the parameter values prompt at runtime. The default delimiter is a space. Values that contain spaces are wrapped in double quotes.

  • Path Selection:
    • Multiple Paths: Allows for selecting multiple items.
    • Single Path: Allows for selecting a single item.
    • Existing Path: Allows for selecting a single item that must already exist on the system at runtime.
  • Specify Extension Filters: If checked, allows you to apply filters on the filenames that can be selected. Specify the filters in the Filter field, and an optional description in the Description field. Wildcard characters and logical operators are supported in the Filter field. For example, to allow any file with a .shp extension, specify *.shp. To add or remove filters, or move filters higher or lower in the list, click the add (+), remove (-), or directional arrow symbols. To specify more than one condition in the same filter, use the OR operator; for example, *.shp OR *.dbf. To allow any file to be selected, leave this field blank.
  • Restrict URL Schemes: If Items to Select is URL, check this box to specify the URL protocols that are allowed. http and https are listed by default. To specify other protocols, double-click inside an empty row, type the protocol, and press enter. To add or remove protocols, select and click + or -, respectively.
  • Select Single: Allows selecting a single attribute name from a drop-down.
  • Select Multiple: Allows selecting multiple attribute names from a list box.
  • List Support:
    • None: Allows selecting names of both regular attributes and list attributes. However, if a list attribute name is selected, the user is prompted further to select a list element name. Specify this option if the place where the list attribute is used in the workspace does not support list attributes. For example, if the list attribute is used in a Logger transformer, you must specify a list element for the Logger to recognize it as an attribute.
    • Full: Allows selecting names of both regular attributes and list attributes. Specify this option if the place where the list attribute is used in the workspace supports list attributes.
    • Exclusive: Allows selecting only list attribute names. Specify this option to restrict selection only to list attributes, and the place where the list attribute is used in the workspace supports list attributes.
  • Allow New Attributes: If Select Single is specified, this option allows the user to specify a new attribute name instead of selecting an existing attribute.
  • Exclude Incoming: If checked, the user is prevented from selecting names of format and user attributes that originate from any reader feature types.
  • Format Attributes:
    • None: The user is prevented from selecting any format attribute names.
    • Upstream Reader: The user can select format attribute names defined only on reader feature types in the workspace.
    • Downstream Writer: The user can select format attribute names defined only on writer feature types in the workspace.
    • Both: The user can select format attribute names defined on both reader and writer feature types in the workspace.
  • User Attributes:
    • None: The user is prevented from selecting names of any user attributes.
    • Upstream Reader: The user can select names of user attributes defined only on reader feature types in the workspace.
    • Downstream Writer: The user can select names of user attributes defined only on writer feature types in the workspace.
    • Both: The user can select names of user attributes defined on both reader and writer feature types in the workspace.
  • Filter Attributes By Port: Restricts the selection of attributes to those that enter the specified port.
Note  These parameters apply only to workspaces that are run from FME Flow. For more information, see Using the Geometry Parameter in FME Flow (previously FME Server).

You can configure the following parameters if Geometry Encoding is GeoJSON:

  • Geometry Types: The geometries that may be specified. If the coordinates that are entered do not validate to any of the specified geometries, an error is returned.
  • Specify initial bounds for map display: If checked, the interface for entering coordinates is limited to the specified Top, Left, Bottom, and Right coordinates.
  • Python Entry Point: The name of the Python module that accesses resources. The Python package containing the module must be built and installed to FME. For more information, see the FME Packages SDK.
  • Input Parameters: Parameter values required for the Python module to run; for example, the value from a user parameter of type Web Connection that was created to access a web service.
  • Selection Type: Specifies the type of values available for selection:
    • Items: Only files are available for selection.
    • Containers: Only folders are available for selection.
    • Items and Containers: Files and folders are available for selection.
  • Allow Multiple Selection: If checked, more than one value can be selected.
  • Items Have Hierarchy: If checked, the hierarchical path structure is preserved in the presentation of values that are selected.
  • Allow Root Selection: If checked, the root folder of the resource being accessed is available for selection.
  • Container Icon: In the selection dialog, the icon to display with containers.
  • Item Icon: In the selection dialog, the icon to display with files.
  • Supports Search: If checked, a Search field is added to the selection dialog.
  • Name Matches Identifier: If checked, any names of resource values that match their identifiers are not editable in the Advanced Selection Editor. If unchecked, any names of resource values that match their identifiers are editable, while the names of resource values that do not match their identifiers are not editable.
  • Input Constants: Any additional Key-Value data that may be required for the Python module.

If the selected item on the left pane is a group box, and not an individual parameter, you can configure the following:

  • Style:
    • Plain: The group box is neither Collapsible nor Checkable.
    • Collapsible: The group box can be manually expanded and collapsed.
    • Checkable: The group box can be manually expanded and collapsed, and the ability to edit its contents can be toggled with a checkbox.
  • Default State: If Style is Collapsible or Checkable:
    • Automatic: The default state of the group box is either expanded or collapsed, depending on default factors of the operating system.
    • Open: The default state of the group box is expanded.
    • Closed: The default state of the group box is collapsed.
  • Default Checked: If Style is Checkable, and this setting is unchecked, the default state of the group box is unchecked. If this setting is checked, the default state of the group box is checked.
  • Conditional State: If Style is Collapsible, check this setting to control the state of the group box based on the value of another parameter that is provided above the group box. The state of the group box depends on whether the value of the previous parameter specified in the If clause Is or Is Not the specified value. Depending on the results of the If clause, the state of the group box is controlled in the Then and Else clauses as either expanded (Open) or collapsed (Closed).

    • The parameter specified in the If clause must be a type that allows specifying a single value, such as a Yes/No parameter, a specified Text string, or a Choice parameter that does not Allow Multiple Selection.

If Published is checked, you can check this setting to control the visibility of the parameter (or group box) based on the value of another parameter that is provided at runtime prior to this parameter.

The visibility of the parameter depends on whether the value of the previous parameter specified in the If clause meets the condition (Is, Is Not, <, <=, >, >=) relative to a specified value. Depending on the results of the If clause, the visibility of the parameter is controlled in the Then and Else clauses as enabled (Show as Enabled), disabled (Show as Disabled), hidden (Hide), or hidden and disabled (Hide and Disable).

The parameter specified in the If clause must be a type that allows specifying a single value, such as a Yes/No parameter, a specified Text string, or a Choice parameter that does not Allow Multiple Selection.

For more information, see Controlling the Visibility of Published Parameters.

Choose the default value that will be used.

Modifying User Parameters in the Navigator

To edit the default value of a user parameter

Select the parameter, right-click, and select Edit Value. Alternatively, double-click on the parameter.

To edit the default value of multiple user parameters

Right-click on User Parameters, or any single user parameter, and select Edit User Parameter Default Values.

To remove a user parameter

Select a parameter, right-click, and select Delete.  

To apply the value of a user parameter to one or more other parameters

Select the parameter, right-click, and select Apply to.

Tip  If you filter the list by keyword, the list dynamically updates as you enter the keyword.