User Parameters in FME Form

Introduction

When it comes to core FME functionality, parameters are at the heart of things. Parameters allow workspace authors to provide specific instructions to FME's various workspace objects (readers, writers, and transformers) to control how these objects function. Every FME workspace object requires the specification of at least one parameter value before it can be run during a translation.

A workspace object’s parameter values are frequently specified by workspace authors through each object’s Parameters dialog. Parameter values set in this way are fixed at runtime, meaning they will not be accessible to users for value adjustments once a translation is initiated.

Occasionally, the value of a parameter needs to be adjustable at runtime to allow for user control. To meet this need, authors can employ a special type of user parameter called a visible user parameter. This allows the user to specify parameter values at runtime that the author has set to visible user parameters. When a workspace is published to FME Flow, visible user parameters are shown in the run workspace dialog.

This article will start with a brief overview of the user parameters built into FME, and will then focus on visible user parameters. Several exercises are included to demonstrate how visible user parameters can add more flexibility and runtime control to workspaces while safeguarding workspace design.

As of FME 2025.2, the term "Published Parameters" has been renamed in both FME Form and FME Flow.

• In FME Form, "Published Parameters" are now called Visible Parameters and "Private Parameters" are now called Hidden Parameters.
• In FME Flow, "Published Parameters" are now simply called User Parameters.

This terminology is still in the process of changing, so older versions may still reference "Published Parameters".

An Overview of User Parameters in FME

FME user parameters are created and applied to workspace object parameter values by the workspace author. Depending on their configuration, these user parameters may or may not be presented to users in the runtime Translation Parameters Values dialog for value inputs.

The relationship between the User Parameters section in the Navigator window, the canvas objects that reference the user parameters, and the User Parameters group in the runtime Translation Parameters Values dialog. The red boxes highlight one user parameter and where it may appear throughout the workspace.

When a workspace containing a user parameters is run, the value specified for each user parameter in the Translation Parameters Values dialog is passed to the referencing object parameter during translation. In the screenshot above, the user has entered a value of TEST_OUTPUT for the visible user parameter OUTPUT_FEATURECLASS (Label: Output feature class). This value will be subsequently passed to the Shapefile writer feature type parameter referencing the visible user parameter. Once the workspace translation is complete, there will be a new feature class named TEST_OUTPUT in the output folder.

A workspace object parameter that references a user parameter will have a value of $(<Parameter Identifier>) when viewed in the Navigator window, Parameter Editor window, or workspace object’s Parameters dialog. This Parameter Identifier value is specified while creating a new user parameter, as demonstrated in the Creating User Parameters with the Parameter Manager article.

Demonstrating the various workspace locations where a user parameter might be referenced. Any object parameter referencing a user parameter will have a value of $(<Parameter Identifier>)

Many types of user parameters are available in FME. This variety is necessary, as each workspace object parameter expects to receive a specific type of data, but types will vary between object parameters.

For example, in the screenshot above, the TEXT attribute parameter of the AttributeCreator expects to receive a Select Attributes type parameter. The Value parameter of the AttributeCreator, on the other hand, expects to receive a Text type parameter. Providing any type other than the expected type for either of these AttributeCreator parameters may result in errors during translation, as the AttributeCreator may not “know” how to handle another parameter type for these parameter values. More details on FME user parameter types are available in the Parameter Types section of the Creating and Modifying User Parameters FME documentation.

The TEXT user parameter from the AttributeCreator viewed in the Parameter Manager dialog. This user parameter must be of type Select Attributes to function correctly in the AttributeCreator, as this is the type expected by the target object parameter

Hidden and Visible User Parameters

There are two main subcategories of user parameters in FME: hidden and visible. This is controlled by the Visibility setting when creating user parameters. Visible parameters can be set to Conditionally Visible which sets the visibility of the parameter based on the value of one or more parameters provided at runtime, prior to this parameter. To learn more about Conditionally Visible user parameters, see the Controlling Parameter Visibility documentation.

Hidden User Parameters

A hidden user parameter is only shown to the workspace author and is not exposed to the workspace user in the Translation Parameters Values dialog at runtime. Instead, these parameters are accessible via the Navigator window of a workspace, under the User Parameters section. Hidden parameters exist under a Hidden Parameter heading within the User Parameters section of the Navigator and can be distinguished from visible parameters by the padlock icon to the left of their name.

A single hidden user parameter under the Hidden User parameters heading within the User Parameters section of the Navigator window. Note the padlock on the hidden parameter’s icon, indicating that its value is locked for editing at runtime.

Hidden user parameters are often used to quickly access and adjust specific object parameter values, which require frequent changes in complex workspaces. Rather than repeatedly searching through a busy workspace for the same specific parameter value(s) to adjust, authors can apply a hidden parameter to these frequently adjusted values and simply edit the referenced hidden parameter from the Navigator window.

Visible User Parameters

Visible user parameters will also appear in the User Parameters node of the Navigator window, denoted by the half gear icon with an arrow rather than a padlock. These parameters are visible in the runtime Translation Parameters Values dialog when the workspace is run with Prompt for Parameters enabled.

The Translation Parameters Values dialog with the TEXT visible user parameter shown at runtime. The visible user parameter’s Label value (Text attribute) is displayed instead of its Parameter Identifier value in the Translation Parameters Values dialog. Note the absence of the TEXT_VALUE hidden user parameter from theTranslation Parameters Values dialog.

Users can conveniently input a value for each visible parameter right from the runtime Translation Parameters Values dialog. These user-provided values will then be passed to the workspace objects, which reference each user parameter. In this way, users can control and adjust the parameter values of workspace objects at runtime rather than remaining fixed by the workspace author. This runtime flexibility moves some translation control to the workspace user without authors needing to grant workspace editing privileges to users.

Visible user parameters and their applications will be the focus of the remainder of this article.

Creating User Parameters

In FME Workbench, user parameters can be created from the following locations:

the Parameter Manager
the Parameters dialog of a workspace object
the Parameter Editor window

How each user parameter is created largely depends on its intended use and so is at the discretion of the workspace author. There are, however, two broad best practices to consider when creating new user parameters:

If the workspace author has a comprehensive understanding of parameter types and is, therefore, able to create a user parameter that meets the target workspace object parameter requirements. This method is beneficial when creating several user parameters for a workflow or applying a single user parameter to multiple workspace objects parameters. Please see Method 1 below, for more details.
For beginner FME workspace authors, it is recommended to create user parameters from within the target object’s Parameters dialog, or from the Parameter Editor window. This creation method will ensure that the resulting user parameter’s type matches the type expected by the target object parameter. Please see Method 2 below, for more details.

For a detailed tutorial on each method, please follow:

Method 1: Create User Parameters with the Parameter Manager

The Parameter Manager offers a convenient way to create new user parameters if workspace authors:

need to create a single user parameter that will be applied to multiple workspace object parameters or are required to create several user parameters for a given workflow
thoroughly understand the parameter types expected by their target workspace object parameters

Authors can access the Parameter Manager by:

Right-clicking on the User Parameters section of the Navigator window and selecting Manage User Parameters
Adding the Manage User Parameters quick access icon to the main Workbench toolbar, and then clicking on it.
- Open FME Options > Toolbar > Available Actions > Build > Double-click Manage User Parameters

The Parameter Manager opens in its own two-sided dialog. The left-side pane shows a list of user parameters that have already been created for the workspace. Highlighting one of these listed parameters will populate the right-side pane with the selected parameter’s definition.

A group of buttons for managing the listed user parameters is at the top of the left-side pane. Authors can create a new user parameter in the Parameter Manager by selecting the green plus icon, and then choosing the type of user parameter needed from the drop-down list.

Selecting a parameter type from this list will add a parameter entry to the left-side pane, whose default definition will appear in the right-side window for editing.

For an in-depth tutorial on this method, see the Creating User Parameters with the Parameter Manager article.

Method 2: Create User Parameters with the Parameter Editor

Workspace authors can readily create user parameters from the Parameter Editor or Parameters dialog of any workspace object added to the canvas. Most of the parameters in these dialogs have a drop-down arrow to their right. Selecting this drop-down arrow provides access to a variety of options for setting an object parameter’s value.

One of these options is User Parameter. Selecting User Parameter from this drop-down menu will display a secondary set of options, where authors can choose Create User Parameter. Selecting Create User Parameter in this secondary menu will open the Add/Edit User Parameter dialog.

Here, users can define a new user parameter whose type will, by default, match the type expected by the target workspace parameter. User parameters created in this way are visible user parameters unless the author selects the “Always Hide” option under Visibility. Once a user defines the new parameter and selects OK on both the Add/Edit User Parameter dialog and on the subsequent dialog, a new user parameter will appear in the User Parameters node of the Navigator window.

In the example above, a new user parameter was created from the Open File Geodatabase reader’s Edit dialog by selecting the drop-down menu to the right of the reader’s Coordinate System parameter. This new user parameter is by default a Coordinate System type parameter, matching the type that the target parameter of the reader expects.

This method of creating visible user parameters is also available to authors from the Parameter Editor window. In FME Workbench, select View > Windows > Parameter Editor to enable the dockable Parameter Editor window.

With the Parameter Editor window visible (docked or undocked), authors can select any object on the canvas, and the selected object’s parameters will be available for editing in the Parameter Editor window.

Authors can select the drop-down arrow next to parameters displayed in the Parameter Editor window to access the User Parameter > Create User Parameter menu option discussed above.

This method of creating visible user parameters is the best way to ensure each user parameter meets the parameter type needs of its target workspace object parameter. As such, this method should be used preferentially to Method 1 (Parameter Manager) where feasible.

For an in-depth tutorial on this method, see the Creating User Parameters with the Parameter Editor article.

Combining User Parameters

Occasionally, it’s beneficial to combine the value of a user parameter with the value of another parameter in a workspace.

This parameter value concatenation is particularly useful when constructing database queries, as it allows the workspace user to control a portion of the query at runtime.

View the Combining User Parameters article for a step-by-step tutorial.

Grouping Feature Types into Themes with User Parameters

A workspace author may want to give users the ability to filter reader source data by thematic group, each consisting of several feature types.

For example, a Transportation thematic group might include a Rail and a Road table, and a Water thematic group might include separate geodatabase feature classes for Streams, Rivers, and Lakes. This approach is particularly useful for FME Flow jobs, where users often want to select data for download by thematic group rather than by file.

Using the Feature Types to Read parameter of a reader, authors can configure a unique type of Choice user parameter to define thematic groups and assign multiple feature types to each group. The thematic groups are presented to users as choice options at runtime; choosing a particular thematic group will assign the associated feature types as the value for this user parameter and, thus, the value for the Feature Types to Read parameter of the reader.

View the Grouping Feature Types into Themes with User Parameters article for a step-by-step tutorial.

User Parameters FAQ

Can I pass a user parameter value into a workspace when calling the workspace from the command line?

Absolutely! The syntax is:

--<parameter name> <parameter value>

Note the single space between <parameter name> and <parameter value>; this syntax is important.

Let’s say the goal is to run a workspace named SetRoadWidth.fmw from the command line, where a value for a visible user parameter called RoadWidth is required. The command line syntax to run the workspace would be:

`fme.exe SetRoadWidth.fmw`
--RoadWidth 22

A successful translation run from the command line will still display the typical Translation was SUCCESSFUL message when complete.

Can I create a visible user parameter that receives its valid value options dynamically from an existing dataset?

Yes, it is possible to dynamically set a value for a parameter, using a scripted user parameter. However, it is not possible to dynamically generate a list of options for a user to select from at runtime using FME Form alone. This can be done in FME Flow using a workspace which gathers a list of options from a source dataset of interest, and then providing this list of options as part of a Flow app.

The first step involves building and running a workspace which scans the source dataset to pull out the relevant information (such as feature types or attribute names), and then generates the list of parameter value options that users will see.

The second step would involve providing a way for users to make their selection from that list and then pass that selection into a second child workspace, which performs actions based on this selection. An FME Flow app could readily meet this need. More information on FME Flow apps can be found in our Getting Started with FME Flow Apps article series.