Published 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 during workspace authoring by accessing 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 some user control over the flow of data through a workspace. It’s necessary that these parameter values are not fixed by the workspace author but instead specified by the workspace user at runtime. To meet this need, authors can employ a special type of user parameter called a published parameter.

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

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 workspace users in the runtime Parameter Prompt for value inputs.

The relationship between the User Parameters node in the Navigator window, the canvas objects that reference the user parameters, and the User Parameters group in the runtime Parameter Prompt. The blue underline highlights one user parameter and where it may appear throughout the workspace.

When a workspace containing user parameters is run, the value specified for each user parameter in the Parameter Prompt is passed to the referencing object parameter during translation. In the screenshot above, the user has entered a value of BigIntTest for the published user parameter NEW_FEATURECLASS_NAME. This value will be subsequently passed to the file geodatabase reader feature type parameter referencing the published parameter. Once the workspace translation is complete, there will be a new feature class named BigIntTest in the written file geodatabase. 

A workspace object parameter that references a user parameter will have a value of $(User Parameter ID) when viewed in the Navigator window, the Parameter Editor window, or the workspace object’s Parameters dialog. This User Parameter ID value is specified while creating a new user parameter, as demonstrated in Exercise 1 below. 

Demonstrating the various workspace locations where user parameter references might be found for a given canvas object. Any object parameter referencing a user parameter will have a value of $(User Parameter ID)

Many types of user parameters are available in FME. This variety is necessary, as each individual workspace object parameter expects to receive a specific type of value, but types will vary between object parameters. For example, the Output Attribute parameter of the AttributeCreator, in the screenshot above, expects to receive an Attribute Name-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 this FME documentation. 

The OUTPUTATTR_NAME user parameter is viewed in the Parameter Manager dialog. It must be of type Attribute Name to function correctly with the Output Attribute parameter of the AttributeCreator, as this is the type expected by the target object parameter

Private and Published User Parameters

There are two main subcategories of user parameters in FME: private and published. A private user parameter is only visible to the workspace author and is not exposed to the workspace user in the Parameter Prompt at runtime. Instead, these private parameters are accessible via the Navigator window of a workspace, under the User Parameters node. Private parameters are distinguished from published parameters by the padlock icon to the left of their name in the User Parameters node.

A single private parameter in the User Parameters node of the Navigator window. Note the padlock on the private parameter’s icon, indicating that its value is locked for editing at runtime

Private 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 private parameter to these frequently adjusted values and simply edit the referenced private parameter from the Navigator window.

Published user parameters will also appear in the User Parameters node of the Navigator window, denoted by the half gear icon with an arrow in lieu of a padlock. These parameters are “published to”, or displayed in, the runtime Parameter Prompt when the workspace is run with Prompt for Parameters enabled. 

The OUTPUTATTR_NAME published user parameter as it appears in the runtime Parameter Prompt dialog. The published parameter’s Prompt value is displayed instead of its ID value in the Parameter Prompt dialog. Note the absence of the REPLACE_TEXT private user parameter from the Parameter Prompt dialog

Users can conveniently input a value for each published parameter right from the runtime Parameter Prompt. These user-provided values will then be passed to the workspace objects, which reference each published 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. Published parameters and their applications will be the focus of the remainder of this article. 

Creating Published Parameters

In FME Workbench, published parameters can be created from:

• the Parameters dialog of a workspace object;
• the Parameter Editor window; or
• the Parameter Manager 

How each published 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 published parameters:

• If a published parameter will be applied to more than one target object parameter, it is referred to as a shared published parameter. Shared published parameters are best created in the Parameter Manager. Care must be taken to ensure the shared published parameter’s type meets the type requirements of all of its target workspace object parameters. Please see Method 1 below, for more details.
• If a published parameter will only be applied to one target workspace object parameter, it is recommended to create this published parameter from within the target object’s Parameters dialog, or from the Parameter Editor window. This creation method will ensure that the resulting published parameter’s type matches the type expected by the target object parameter. Please see Method 2 below, for more details.

Method 1: Create Published Parameters from the Parameter Manager

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

• need to create shared published parameters or are required to create several user parameters for a given workflow; and 
• thoroughly understand the parameter type(s) expected by their target workspace object parameters

It is important for authors to have a good understanding of the parameter type requirements of target workspace object parameters, as translation errors will occur if an incorrect parameter type is passed to a workspace object parameter. For this reason, published parameter creation via the Parameter Manager should be considered an intermediate-level user task. 

Authors can access the Parameter Manager by:

• Right-clicking on the User Parameters node of the Navigator window and selecting Manage User Parameters; or
• Adding the Manage User Parameters quick access icon to the main Workbench toolbar, and then clicking on it. This icon can be added to the main Workbench toolbar by navigating to Tools → FME Options → Toolbar, then expanding Tools in the Available Actions options. Double-click on the Manage User Parameters icon therein, and then select Apply to add the icon to the main Workbench toolbar. 

Access the Parameter Manager from the Navigator window

Access the Parameter Manager by adding its toolbar icon to the main Workbench surround

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 published parameter in the Parameter Manager by selecting the green plus icon, and then choosing the type of published 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.

Exercise 1: Creating a New Shared Published Parameter from the Parameter Manager

Please download the template workspace, PublishedParameter_Exercise1_Start.fmwt, downloadable Files section along the right-side menu of this article. This workflow reads Vancouver bike path line segments into the workspace, then splits into separate branches to generate two outputs:

• a MapInfo file of bike path segments joined by Path name; and
• a CSV file of bike path statistics

Overview of the starting workspace for Exercise 1

The workspace will be adjusted to make use of a shared published parameter applied to the Dataset parameter of both a CSV and a MapInfo writer. In this way, the written files will be output to the same destination folder, as defined by the user at runtime. 

1. Open PublishedParameter_Exercise1_Start.fmwt in FME Workbench 2024.0

Open PublishedParameter_Exercise1_Start.fmwt in FME Workbench 2024.0 or newer, and save it locally. Saving the workspace will also save the source file geodatabase, VancouverOpenData.gdb, that is included with the template file. The workspace makes use of the Esri Geodatabase (File Geodb Open API) reader, which does not require a valid Esri product license to run.

2. Configure the Workspace Settings and Windows

Configure the workspace settings and windows. First, find the Run icon in the main Workbench toolbar along the top of the canvas; the Run icon is a green right-pointing triangle. Select the drop-down arrow to the right of the Run icon to view the run translation options. If Prompt for Parameters, Enable Feature Caching, and Enable Feature Counting do not have check marks next to them, select each to enable these translation options.

Next, access the View menu found along the top of the Workbench surround. Select Windows, and then enable the Navigator, Translation Log, and Visual Preview windows (if not already enabled). These windows can be docked to the Workbench surround, or left as stand-alone windows for convenience.

Select the Navigator, Translation Log, and Visual Preview options to enable these dockable windows

3. Run the workspace

Run the workspace by selecting the Run icon found in the main Workbench toolbar. With the Prompt for Parameters option enabled, the first action that occurs is the display of the Parameter Prompt dialog with its single published parameter. 

This single parameter is linked to the geodatabase reader’s File Geodatabase parameter and was created by default when the reader was added to the canvas. FME readers and writers typically create published parameters linked to their source or destination dataset to allow users to point to their target datasets at runtime.

Let’s add to this Parameter Prompt dialog by creating a shared published parameter that will allow users to specify a common destination folder for the planned outputs of this workspace.

Select Cancel on the Parameter Prompt to return to the main canvas.

4. Create a New File/Folder/URL Type Published Parameter

Create a new File/Folder/URL type published parameter by first accessing the Parameter Manager. Right-click on the User Parameters node of the Navigator window, and select Manage User Parameters in the menu that displays at right. The Parameter Manager dialog will pop open.

Select the green plus icon at the top left of the Parameter Manager to access the parameter type drop-down. 

Choose the File/Folder/URL parameter type. A new user parameter will appear in the left-side pane of the Parameter Manager, and its default definition will populate in the right-side pane.

With this new parameter highlighted in the left-side pane, configure the parameter definition in the right-side pane as follows:

• Parameter Identifier:  DEST_FOLDER
• Prompt (enabled):  Specify the destination folder for outputs:
• Published - enabled
• Required - enabled; with this enabled, the parameter will have a red asterisk attached to it in the left-side list of the Parameter Manager
• Disable Attribute Assignment - disabled
• Items to Select: Folders
• Access Mode: Write
• Default Value: <leave this blank>

Complete definition of the new File/Folder type published user parameter

5. Select the Preview Button

Select the Preview button, at bottom right of the Parameter Manager, to see how this new published user parameter will look in the runtime Parameter Prompt.

The new File/Folder type published user parameter is denoted in the Parameter Prompt dialog by its Prompt value, not by its Parameter Identifier value. The value of this new published parameter shows up highlighted in red, indicating that a value must be provided for it to allow this translation to run. 

Try selecting the ellipsis next to the new parameter’s value input box to see the functionality of this published parameter type. Users will be able to navigate to a desired destination folder for the CSV and MapInfo files that will be output by this workspace, right at runtime. 

Close the Parameter Preview window, and select OK on the Parameter Manager to return to the main canvas. There should now be a second entry under the User Parameters node of the Navigation window, showing both the Parameter Identifier value and the Prompt value configured for the new File/Folder published parameter.

6. Add a CSV Writer

Add a CSV writer to the canvas by typing CSV in a blank canvas area. Be sure to select the CSV (Comma Separated Values) writer from the Quick-Add Menu that pops up.

In the Add Writer dialog that opens, leave the Dataset parameter blank and the CSV File Definition as Automatic. Click OK.

Next, the Feature Type dialog will open. Set the CSV File Name parameter to JoinedBikePaths, and then select OK. 

A new CSV writer feature type will be added to the canvas. Connect this feature type to the Sorted port of the top-most Sorter, to have the joined bike path segments written to a CSV file.

Next, have a look at the User Parameters node of the Navigator window. There should now be a third user parameter listed, DestDataset_CSV2. This new published user parameter is linked to the Dataset parameter of the newly added CSV writer. This behavior is expected; adding a new reader or writer to a workspace will always result in the creation of a published user parameter linked to the format’s Dataset (or similar) parameter.

7. Apply the DEST_FOLDER Published Parameter to the CSV Writer

Apply the DEST_FOLDER published parameter to the CSV writer. Right-click on the CSV writer in the Navigator window and select Edit. In the Edit dialog that opens, select the down arrow to the right of the Destination CSV Folder parameter and choose User Parameter → DEST_FOLDER. 

Once the DEST_FOLDER user parameter has been applied to the Destination CSV Folder parameter of the reader, the Edit dialog should show the reference to the user parameter as follows:

Select OK in the Edit dialog, and watch the User Parameter node of the Navigator window. The user parameter that was auto-created when the CSV writer was added to the canvas has been deleted, as the writer’s Destination CSV Folder parameter is now referencing a different user parameter. 

This deletion illustrates a key point about user parameter management: if adjustments are made to a workspace such that a user parameter is no longer referenced somewhere in the workspace, the user parameter will be automatically deleted. 

 
8. Add a MapInfo TAB Writer

Add a MapInfo TAB writer to the canvas by typing MapInfo in a blank canvas area. Select the MapInfo TAB (MITAB) writer from the Quick Add menu that appears. The Add Writer dialog will pop open.

In the Add Writer dialog, leave the Dataset parameter blank and the Table Definition parameter as Automatic. Select OK in the Add Writer dialog. 

In the Feature Type dialog that opens, type BikePathStatistics into the Table Name parameter text box, and then select OK.

A new MITAB feature type will appear on the canvas. Connect this feature type to the Sorter_2 Sorted output port. As expected, a new published user parameter will appear in the User Parameter node of the Navigator window, linked to the Destination MapInfo Folder parameter of the MITAB writer.

9. Apply the DEST_FOLDER Published Parameter to the MITAB Writer

Apply the DEST_FOLDER published parameter to the MITAB writer. Right-click on the MITAB writer in the Navigator window and select Edit. In the Edit dialog that opens, click the down arrow next to the Destination MapInfo Folder parameter and choose User Parameter → DEST_FOLDER. Click OK.

10. Run the Workspace

Run the workspace. Select the Run icon along the main Workbench toolbar to initiate the translation. The Parameter Prompt will pop open. Leave the File Geodatabase parameter’s value as-is, and click on the ellipsis next to the DEST_FOLDER parameter’s text box. Navigate to a folder where the written CSV and the MapInfo files can be stored. Click on Select Folder to return to the Parameter Prompt.

Optionally, deselect Save As Parameter Default Values in the Parameter Prompt to ensure the selected folder path does not become the default value for this published parameter. This option is recommended if the workspace will be shared among many users to avoid errors associated with invalid parameter values on different machines/networks.

Now click the Run button at the bottom right of the Parameter Prompt. Observe the translation log messages scrolling through the Translation Log window, watching for the Translation was SUCCESSFUL message. This workspace should result in 21 features being passed into each writer feature type and the written CSV and MapInfo files stored to the location specified by the DEST_FOLDER parameter value. 

11. Save the Workspace

Save the workspace locally, as PublishedParameters_Exercise1_Complete.fmw. Exercise 2, below, will begin with this workspace in its current state.

Method 2: Create Published Parameters From Within a Workspace Object or From the Parameter Editor

Workspace authors can readily create published parameters from the Edit 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 published parameters unless the author deselects the Published checkbox. 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 published parameter will appear in the User Parameters node of the Navigator window. 

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

This method of creating published 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 published user parameters is the best way to ensure each published parameter meets the parameter type needs of its target workspace object parameter. As such, this method should be used preferentially to Method 1 where feasible.

Exercise 2. Creating a New Published Parameter from the Parameter Editor Window and the Parameters Dialog

This exercise builds on the workspace completed in Exercise 1, above. Users who completed Exercise 1 can make use of PublishedParameters_Exercise1_Complete.fmw that was saved locally. Users who did not complete Exercise 1 should download PublishedParameters_Exercise2_Start.fmwt from the downloadable Files section along the right-side menu of this article

1. Open PublishedParameters_Exercise1_Complete.fmw, or PublishedParameters_Exercise2_Start.fmwt in FME Workbench 

Open PublishedParameters_Exercise1_Complete.fmw or PublishedParameters_Exercise2_Start.fmwt in FME Workbench 2024.0 or newer. Both workspaces contain a simple workflow for producing complete bike path features and associated statistics from source bike path line segments. This workflow outputs two files: a CSV file that lists some key details describing each complete bike path and a MapInfo file containing statistics for each bike path.

This workspace will allow users to select a desired destination folder for the written CSV and MapInfo files at runtime. It would be ideal if users could also specify a file name for each written product at runtime. This exercise will walk through the creation of two new published parameters, which will allow users to specify a file name for the CSV and MapInfo files produced by this workspace.

Users beginning with the Exercise 2 .fmwt file should save it locally before continuing with this exercise. Saving the Exercise 2 workspace will also save the accompanying file geodatabase to the same location.

2. Configure the Workspace Settings and Windows

Configure the workspace settings and windows. First, find the Run icon in the main Workbench toolbar along the top of the canvas; the Run icon is a green right-pointing triangle. Select the drop-down arrow to the right of the Run icon to view the run translation options. If Prompt for Parameters, Enable Feature Caching, and Enable Feature Counting do not have check marks next to them, select each to enable these translation options.

Next, access the View menu. Select Windows, and then enable the Navigator, Translation Log, Visual Preview, and Parameter Editor windows (if not already enabled). These windows can be docked to the FME Workbench, or left as stand-alone windows. Optionally dock the Navigator, Translation Log, and Visual Preview windows, but leave the Parameter Editor window undocked for convenience during the following steps.

3. Select the CSV Writer Feature Type on the Canvas

Select the CSV writer feature type on the canvas, called JoinedBikePaths, with a single click. Now, have a look at the Parameter Editor window; the parameters associated with the selected CSV writer feature type are now visible and editable therein.

The task is to give users the ability to specify a file name for each written product at runtime. To accomplish this task, a published parameter should be applied to the file name parameter of each writer feature type. For the CSV writer feature type, the published parameter will be applied to the CSV File Name parameter.

4. Create a Published Parameter from the Parameter Editor Window

Create a Published Parameter from the Parameter Editor window. Ensure the CSV writer feature type is still selected on the canvas. In the Parameter Editor window, select the down arrow next to the CSV File Name parameter’s text box, and choose User Parameter → Create User Parameter. The Add/Edit User Parameter dialog will open.

Configure the Add/Edit User Parameter dialog values as follows:

• Parameter Identifier: CSV_FILENAME
• Prompt (be sure it is enabled): Enter a file name for the CSV output:     
• Published - enabled
• Required - enabled
• Disable Attribute Assignment - disabled
• Conditional Visibility - disabled
• Default Value - select the down arrow next to its text box, and choose Clear Value. Leave it blank.

Click OK on the Add/Edit User Parameter dialog, and then look at the value of the CSV File Name parameter in the Parameter Editor window. The CSV File Name parameter is now referencing the newly created CSV_FILENAME published parameter, as indicated by its new $(CSV_FILENAME) value. Creating published parameters in this way will automatically apply them to the appropriate target object parameter value.

Now select Apply at the bottom right of the Parameter Editor window to commit the parameter edits. This action will add the newly created CSV_FILENAME published parameter to the User Parameters node of the Navigator window.

5. Create a Published Parameter from the Parameters Dialog

Create a published parameter from the parameters dialog of the MapInfo TAB writer feature type. Double-click on the MapInfo TAB writer feature type to open its Feature Type parameters dialog. The written MapInfo file name is determined by the Table Name parameter, so let’s apply a published parameter to the Table Name value.

Select the down arrow to the right of the Table Name parameter’s text box, and choose User Parameter → Create User Parameter. This action will open the Add/Edit User Parameter dialog, similar to Step 4 above.

Configure the Add/Edit User Parameter dialog values as follows:

• Parameter Identifier: MITAB_FILENAME
• Prompt (be sure it is enabled): Enter a file name for the MapInfo output:     
• Published - enabled
• Required - enabled
• Disable Attribute Assignment - disabled
• Conditional Visibility - disabled
• Default Value - select the down arrow next to its text box, and choose Clear Value. Leave it blank.

Click OK on the Add/Edit User Parameter dialog, and then look at the value of the Table Name parameter in the Feature Type parameters dialog. The Table Name parameter is now referencing the newly created MITAB_FILENAME published parameter. 

Click OK on the Feature Type parameters dialog. The new MITAB_FILENAME published parameter will appear under the User Parameters node of the Navigator window.

6. Run the Workspace

Run the workspace. Select the Run icon in the main Workbench toolbar to initiate the translation. The first action that will occur is the appearance of the Parameter Prompt.

Click on the ellipsis next to the destination folder parameter and navigate to a folder where the written CSV and the MapInfo files can be saved. Click on Select Folder to return to the Parameter Prompt. 
Next, enter a name for the soon-to-be written CSV and MapInfo files by typing directly into the two remaining user parameter text boxes.

Optionally, deselect Save As Parameter Default Values to ensure these parameter values do not become the default values for these published parameters. Deselecting this option is recommended if the workspace will be shared amongst many users, to avoid errors associated with invalid parameter values.

Now select the Run button, at bottom right of the Parameter Prompt. Observe the translation log messages scrolling through the Translation Log window, watching for the Translation was SUCCESSFUL message. This workspace should result in 21 features being passed into each writer feature type, and the written CSV and MapInfo files should have file names which correspond to the values specified in the Parameter Prompt.  

7. Save the Workspace

Save the workspace locally, as PublishedParameters_Exercise2_Complete.fmw.

Optional Exercise: Create and Apply a Yes / No Published Parameter

This exercise will demonstrate how a Yes/No published parameter can be applied to change the flow of data through a workspace. This user parameter type can be thought of as a workspace switch, where data will be directed to different workflows based on a user’s answer to a yes/no question posed at runtime.

Often, a Yes/No published parameter is referenced in a Tester or TestFilter transformer to split the flow of data into two or more possible branches. This functionality allows a variety of data transformation options to be executed in one workspace.

This optional exercise begins where Exercise 2, above, ended. Users who completed Exercise 2 can make use of their finished Exercise 2 workspace, PublishedParameters_Exercise2_Complete.fmw. Users who did not complete Exercise 2 should download the template workspace, PublishedParameters_OptionalExercise_Start.fmwt, from the downloadable Files section along the right-side menu of this article

1. Open PublishedParameters_Exercise2_Complete.fmw or PublishedParameters_OptionalExercise_Start.fmwt in FME Workbench

Open PublishedParameters_Exercise2_Complete.fmw or PublishedParameters_OptionalExercise_Start.fmwt in FME Workbench 2024.0 or newer. This workspace shows two data streams branching from a file geodatabase reader feature type. The source feature class, BikePathSegments, contains a series of line segments corresponding to well-known biking paths found throughout Vancouver, BC. 

Right now, this workspace produces a CSV file of the bike path segments aggregated by path name and a MapInfo file highlighting some key statistics of each named bike path. Let’s adjust the workspace to let users choose whether to generate bike path statistics.

2. Configure the Workspace Settings and Windows

Configure the workspace settings and windows. First, find the Run icon in the main Workbench toolbar along the top of the canvas; the Run icon is a green right-pointing triangle. Select the drop-down arrow to the right of the Run icon to view the run translation options. If Prompt for Parameters, Enable Feature Caching, and Enable Feature Counting do not have check marks next to them, select each to enable these translation options.

Next, access the View menu found along the top of the Workbench surround. Select Windows, and then enable the Navigator, Translation Log, and Visual Preview windows (if not already enabled). These windows can be docked by dragging them close to the Workbench surround, or can be left as stand-alone windows. 

3. Create a Yes/No Published Parameter from the Parameter Manager

Create a Yes/No published parameter from the Parameter Manager by first right-clicking on the User Parameters node in the Navigator window. Select Manage User Parameters from the options presented. The Parameter Manager dialog will open. 

Select the green plus at the top left of the User Parameter editor to view the list of user parameter types available. Choose the Yes/No user parameter type.

Once the Yes/No user parameter type is selected from the drop-down list, a new Yes/No user parameter will appear in the left-side pane of the Parameter Manager. Highlight this new parameter to access its definition in the right-side pane.

Fill in the right-side parameter definition as follows:

• Parameter Identifier: CALCULATE_PATHSTATS
• Prompt: Do you want to calculate bike path statistics (MapInfo output)?
• Leave all other values for this parameter’s definition as their defaults.
  • Important to note is the value that this parameter will be set to when Checked or Unchecked at runtime. These values are specified by the Checked Value and Unchecked Value definition parameters, respectively.

Select Preview at the bottom right of the Parameter Manager. A preview window will pop up, displaying what users will see in the Parameter Prompt at runtime.

The Yes/No parameter’s Prompt text will appear in the runtime Parameter Prompt. Selecting the checkbox next to this prompt will set this parameter’s value to YES, while leaving the box unchecked will set the parameter’s value to NO.

Close the preview window, and select OK on the Parameter Manager dialog to accept the new Yes/No published parameter’s definition and return to the main canvas. A new user parameter, CALCULATE_PATHSTATS, will appear under the User Parameters node of the Navigator window.

4. Add a Tester Transformer to the Workspace

Add a Tester transformer to the workspace by typing “Tester” in a blank area of the canvas. Select the Tester from the Quick Add dialog that pops up. A new Tester transformer will appear on the canvas.
Position the Tester just to the right of the reader feature type. Now drag the connection line between the reader feature type and the Aggregater so that the reader feature type is connected to the input port of the Tester. Connect both the Passed port and Failed port of the Tester to the input port of the Aggregator.

Finally, drag the connection line between the reader feature type and the StatisticsCalculator so that the StatisticsCalculator's input port is connected to the Tester's Passed output port. Please refer to the screenshot below for assistance in making this adjustment; color has been applied to the connection lines for clarity. 

Adding the Tester to the canvas. The green connection lines show which canvas objects should be connected to the Tester's Passed port, while the red connection line shows how the Tester's Failed port should be connected.

Let’s now define the Tester’s condition so that source features will only reach the StatisticsCalculator if the value of the Yes/No published parameter is YES (i.e. the user checks the Yes/No parameter’s checkbox at runtime). 

First, double-click on the newly added Tester transformer to access its parameters dialog. Set the Left Value to reference the CALCULATE_PATHSTATS Yes/No published parameter. This can be done by single-clicking the Left Value input cell, and then selecting the down arrow that appears to its right. Select User Parameter → CALCULATE_PATHSTATS. 

Alternatively, authors can reference the value of this published parameter by directly typing $(CALCULATE_PATHSTATS) in the Left Value input box.

Complete the test condition by setting the Operator to = and the Right Value to YES. Note that unless the value of the Tester’s Comparison Mode is set to Case Insensitive, the YES Right Value must be uppercase for this test condition to function as expected with the Yes/No published parameter. 

Select OK on the Tester Parameters dialog to accept the test condition's definition and return to the main canvas.

5. Run the Workspace

Run the workspace by selecting the Run icon along the main Workbench toolbar. The Parameter Prompt dialog will pop up. 

The new Yes/No published parameter is clearly in place, but something still does not look quite right with the way these published parameters are presented in the Parameter Prompt. The Yes/No published parameter will allow users to determine if bike path statistics should be calculated and written to a MapInfo file. If a user chooses to forgo generating statistics, they should not have to enter a MapInfo file name to get this workspace to run. However, in its current state, this workspace will only run if a value is entered for the MapInfo file name parameter.

It would be ideal if this MapInfo file name parameter could be disabled, or even hidden, in the Parameter Prompt when the user chooses not to generate statistics. This is where the Conditional Visibility configuration options for published parameters become useful. Let’s adjust the visibility of the MapInfo file name published parameter so that it is hidden in the Parameter Prompt when the user leaves the option to generate statistics unchecked at runtime.

Select Cancel on the Parameter Prompt dialog to return to the canvas.

6. Adjust the MapInfo Published Parameter’s Visibility 

Adjust the MapInfo published parameter’s visibility by first right-clicking on the User Parameters node of the Navigator window. Select Manage User Parameters to open the Parameter Manager.

The MapInfo file name published parameter should be the last item in the left-side list of the Parameter Manager. Select this parameter, and then enable the Conditional Visibility configuration option in the right-side parameter definition.

In the Conditional Visibility group, create the following conditional statement by using the available drop-down options:

If CALCULATE_PATHSTATS Is <Checked>
Then Show As Enabled
Else Hide

Now select the Preview button at the bottom right of the Parameter Manager. Leave the Yes/No published parameter unchecked, and notice how the MapInfo file name published parameter is now hidden. 

The generate statistics parameter is unchecked in the Parameter Prompt, and now the MapInfo file name parameter is hidden

Now try checking the Yes/No checkbox, and watch the MapInfo file name published parameter reappear in the Parameter Prompt.

The generate statistics parameter is checked in the Parameter Prompt, and now the MapInfo file name parameter is visible

The MapInfo file name published parameter’s visibility in the Parameter Prompt will now adjust based on whether the user chooses to generate statistics. Close the Parameter Prompt preview dialog, and select OK on the Parameter Manager to commit the visibility change and return to the main canvas.

7. Run the Workspace

Run the workspace by selecting Run from the main Workbench toolbar. When the Parameter Prompt appears, leave the option to generate statistics unchecked. Choose a destination folder for outputs and enter a name for the output CSV file. 

Select Run at the bottom right of the Parameter Prompt, and then watch the main canvas. Notice that the data flow through the workspace does not include the StatisticsCalculator branch.

Including the Yes/No published parameter in this workspace now allows users to skip writing to MapInfo should they not require bike path statistics.

Save the workspace locally as PublishedParameters_OptionalExercise_Complete.fmw.

Concatenating or Combining Published Parameters

Occasionally, it’s beneficial to combine the value of a published 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.

The following exercise demonstrates how to use a published parameter with the WHERE clause of an Esri Geodatabase (File Geodb Open API) reader to give users some control over which database features will be read into the workspace. This workspace does not require a valid Esri produce license to function correctly.

1. Download PublishedParameters_ConcatenateExercise_Start.fmwt

Download PublishedParameters_ConcatenateExercise_Start.fmwt, from the downloadable Files section along the right-side menu of this article. Open the workspace in FME Workbench 2024.0 or newer, and save it locally. A file geodatabase named VancouverOpenData will save alongside the workspace. 

This workspace looks very similar to the workspace saved after completing the Optional Exercise, above, except the geodatabase reader now has a WHERE clause specified on its feature type. The source data still consists of the same Vancouver, BC, bike path line segments used in the previous exercises.

In its current state, this workspace will read all line segments stored in the Bike Paths feature class of the source file geodatabase. Let’s create a published parameter that will allow users to choose which line segments they would like to read into the workspace by bike path name. In this way, if a user is only interested in working with a single bike path or a subset of paths, they won’t be required to read extraneous data into the workspace. 

2. Expand the Esri Geodatabase Reader Feature Type Parameters in the Navigator Window

Expand the Esri Geodatabase reader feature type parameters in the Navigator window, as shown in the following image, to view the feature type’s configured WHERE clause.

This WHERE clause is currently not adjustable at runtime, so the reader will only bring in those bike path line segments whose PathName attribute value is ‘Ontario’. The task is to give users the ability to choose the value for PathName at runtime, so this WHERE clause needs a published parameter applied to it. 

3. Add a Choice-Type Published Parameter

To add a choice-type published parameter to the workspace, right-click on the User Parameters node in the Navigator window and select Manage User Parameters. In the Parameter Manager dialog that opens, select the green plus icon at the top left and choose the Choice option from the drop-down menu.

A new user parameter will appear in the Parameter Manager's left-side list, and its default definition will appear in the right-side display. If the newly added Choice-type parameter is not already highlighted at the left, select it and then click the Move Up icon (to the right of the green plus icon) once. 

This will move the new choice parameter up one position in the left-side parameter list. The order in which published parameters appear in the Parameter Manager is reflective of the order in which they will appear in the runtime Parameter Prompt. It’s useful to have parameters ordered based on when they perform their actions during translation, just to reinforce where a particular published parameter is likely referenced in the workspace. Since the File Geodatabase parameter and the new choice-type parameter are both related to the reader, and the reader is actioned first in the workspace, having these two published parameters appear first and second in the Parameter Prompt makes sense.

The remaining published parameters can be repositioned similarly, using the icons to the right of the green plus Insert icon. Once reordering is finished, the list of published parameters in the left-side display of the Parameter Manager should look like the following image:

 
Optionally, select the Preview button at the bottom right of the Parameter Manager to view how the reordered published user parameters will look in the runtime Parameter Prompt. When finished previewing, be sure to close the Parameter Prompt preview but leave the Parameter Manager open.

4. Define the new Choice-Type Published Parameter

Define the new Choice-type published parameter that was added in Step 4. Select the choice-type parameter from the left-side display, and then configure the right-side parameter definition as follows: 

• Parameter Identifier: PATHNAMES
• Prompt: Choose bike path(s) to read into the workspace, by path name:
• Published: enabled
• Required: enabled
• Disable Attribute Assignment: enabled  
• Choice Configuration - List

In the Choices table, workspace authors specify the valid options that users can select for this parameter at runtime and the underlying value assigned to these options. The Display column should list the choice options that users will see for this parameter in the runtime Parameter Prompt, while the Value column should list the corresponding value assigned to this parameter for each display option that the user selects.

The Value text entries often correspond to the actual attribute values of some dataset of interest; this is the case for this exercise. Care must be taken to ensure the Value text exactly matches the target attribute values from the dataset of interest.

Value and Display options can be manually entered into the Choices column cells. However, this exercise's source dataset includes several bike path names, and manually typing all of these path names into the Choices table is time-consuming and introduces a source of error. To ensure that these bike path names are entered into the Display and Value columns accurately, importing the names directly from the source dataset would be better.

Select the Import button at the bottom-right of the Choices table, and choose From Dataset.

The Import Wizard will pop open. On the Select Source Dataset dialog, choose Esri Geodatabase (File Geodb Open API) as the Format, and point the Dataset parameter to the workspace’s source file geodatabase. Then, select the Parameters button to access the Esri Geodatabase Parameters dialog.

In the Parameters dialog that opens, click the ellipsis next to the Tables parameter to open the Select Tables dialog. From the list of tables presented, choose the BikePathSegments table. It should be the first option listed in the Select Tables dialog. 

Click OK on the Select Tables dialog and then OK again on the Parameters dialog to return to the Select Source Dataset dialog. Select Next on the bottom right of the Source Dataset dialog to move to the Import Mode dialog of the Import Wizard.

Choose Import from Attribute values on the Import Mode dialog, and click Next.

On the Select Attributes dialog that opens, configure the following:

• Value: PathName
• Display: PathName
• Import Order: Sort by Value

Select Import at the bottom right of the Select Attributes dialog of the Import Wizard. This action will return the active display to the Parameter Manager. Notice how the Value and Display options in the Choices table of the new choice-type published parameter have been populated with the values of the selected PathName attribute.

As shown in the above image, enable the Allow Multiple Selection option to let users choose one or many bike path names of interest at runtime. Now click inside of the Choice List Delimiter input box, and type / copy-paste the following:

‘, ’ 

Please ensure there is a space between the comma and the final single quote in the delimiter. This custom delimiter will ensure that the list of chosen bike path names meets the syntax requirements of a valid SQL query. This point is an important one, since the value of this published parameter will be applied to the SQL WHERE clause of the File Geodatabase reader feature type. Providing the WHERE clause with improper SQL syntax will lead to translation errors.

Leave all other settings as defaults. Use the icons along the top of the left-side pane to re-order the user parameter list such that the new choice-type published user parameter sits immediately below the File Geodatabase published parameter.

Now select the Preview button at the bottom right of the Parameter Manager. The Parameter Prompt preview dialog will pop up.

The new choice-type published parameter appears in the Parameter Prompt, just below the File Geodatabase parameter. Select the ellipsis to the right of the choice-type parameter to view the configured choice list.

Users will be able to select as many of these bike path names as needed at runtime. The value assigned to the PATHNAMES user parameter will be a custom delimited string of user-selected path names in the form of:

'Adanac’, ‘Balaclava’, ‘Burrard’,  *Note: the custom delimiter is not appended to the final list item. 

Click Cancel on the Select Items dialog. Click Close on the Parameter Preview dialog. Click OK on the Parameter Manager to save the new choice-type parameter and return to the canvas. The new PATHNAMES published parameter will appear under the User Parameter node of the Navigator window.

5. Apply the New Choice Published Parameter

Apply the new choice published parameter to the WHERE clause of the File Geodatabase reader. Expand the File Geodatabase reader’s parameters to access the Feature Types node. Then,, consecutively expand the Feature Types, BikePathSegments, Parameters, and Format nodes to view the feature type’s WHERE clause.

Right now, the WHERE clause restricts the reader to reading only those bike path segments whose PathName value is exactly ‘Ontario’. Let’s adjust this WHERE clause to make use of the new choice-type published parameter.

First, double-click on the WHERE clause in the Navigator window to access the Feature Type dialog. Make sure the Parameters tab is active, and then select the ellipsis to the right of the WHERE Clause parameter.

The WHERE Clause editor will open, displaying the current static WHERE clause that is in place. Delete this WHERE clause and replace it with the following:

"PathName" IN ('$(PATHNAMES)')

Now the WHERE clause is referencing the value of the new choice published parameter by including $(PATHNAMES). The WHERE clause will also accommodate multiple bike path name selections with the use of the IN operator. Correct SQL query syntax is ensured by surrounding the parameter reference with the required additional characters.

Select OK on the WHERE Clause editor dialog, and then choose OK on the Feature Type dialog to return to the main canvas.

6. Run the Workspace

Run the workspace. When the Parameter Prompt dialog appears, ensure the File Geodatabase parameter is pointing to VancouverOpenData.gdb. Choose at least two path name options for the list choice parameter, but do not select all path names. Choose to include path statistics, provide a folder destination and file names for the outputs, and disable the Save As Parameter Default Values option at bottom left.

 
Select Run, and watch the feature count on the connection line between the reader feature type and the Tester. There are 489 line segment features in the source feature class; since the WHERE clause was applied to create a subset of the source features, the feature count shown between the reader feature type and the Tester should be less than 489. The feature count shown between the Aggregator and the Sorter should be equal to the number of unique path names selected at runtime.

Feature counts that are produced by selecting Cadero, Homer, and Trafalgar for the new PATHNAMES published parameter at runtime

Save the workspace as PublishedParameters_ConcatenateFinished.fmw. With this choice-type published parameter applied to the file geodatabase's WHERE clause, users can select only those bike paths they would like to read into the workspace, thereby avoiding extraneous data processing. 

Grouping Layers or Feature Types into Themes with Published 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, the transportation thematic group might include a Rail and a Road table, and the 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 published 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 published parameter and, thus, the value for the Feature Types to Read parameter of the reader.

The following exercise demonstrates how to create and apply this unique choice published user parameter in order to group reader feature types into thematic groups of interest and then read data into the workspace by thematic group.

1. Download PublishedParameters_ThematicGroups_Start.fmwt

Download PublishedParameters_ThematicGroups_Start.fmwt from the downloadable Files section along the right-side menu of this article, and save it locally. A file geodatabase, VancouverOpenData.gdb, will save alongside the workspace.

This workspace contains a single Esri Geodatabase (File Geodb Open API) reader, pointing to a file geodatabase whose feature classes include features related to City of Vancouver transportation, water, and cultural features. The reader is currently configured to read all of the geodatabase’s feature classes into the workspace, as individual feature types. Let’s adjust the reader’s Feature Types to Read parameter so that users can choose to read feature classes from the geodatabase by thematic group, where the thematic groups will include Transportation, Water, and Cultural choices.

2. Create a Choice Published Parameter From the Navigator Window

Create a choice published parameter from the Navigator window. First, expand the VancouverOpenData reader fully in the Navigator window by clicking the drop-down arrows beside VancouverOpenData [FILEGDB], Parameters, and then Features to Read consecutively.

Under the Features to Read node resides the Feature Types to Read parameter. Right-click on this Feature Types to Read parameter, and choose Create User Parameter. The Modify Feature Types List dialog will open, and will allow for the definition of a new Choice-type user parameter.

Enable the Use Alternate Display Name option at the top of the Feature Type List to access a Display Name column.

This Display Name column shown here serves the same purpose as the Display column configured for a typical choice-type user parameter. Values entered in this column will be presented to workspace users as choice options at runtime. The Feature Type column shown here serves the same purpose as the Value column configured for a choice-type user parameter. When a user selects a Display Name choice at runtime for this published parameter, the value(s) in the Feature Type column associated with the chosen Display Name will be set as the value(s) for the user parameter. 

One Display Name value can be assigned to more than one Feature Type value. Authors can readily create thematic groups by manually entering the name of a thematic group of interest (eg. Water) into the Display Name column of each Feature Type associated with the thematic group (eg. Rivers, Streams, Lakes). Essentially, authors can create a 1:M relationship between Display Name value and Feature Type value.  

Create three thematic groups of reader feature types by manually entering the value Transport, Water, or Cultural into the Display Name column of each Feature Type value as follows:

• set Transport as the Display Name value for the following Feature Types:
  
  • BikePathSegments
  • bikeways
  • public_streets
  • snow_removal_routes
  • street_intersections
• set Water as the Display Name value for the following Feature Types:
  
  • drinking_fountains
  • public_washrooms
  • sewer_mains
  • sewer_manholes
  • water_distribution_mains
• set Cultural as the Display Name value for the following Feature Types:
  
  • cultural_spaces
  • libraries
  • public_art

Under the Parameter Definition section of the dialog, enter the following:

• Name: THEMATIC_GROUPS
• Prompt: Choose a thematic group of features to read:
• Default Value: <leave blank>

Select OK to accept the definition of this new choice-type published user parameter and return to the main canvas. The new user parameter, THEMATIC_GROUPS, will now appear under the User Parameter node of the Navigator window. The value of the geodatabase reader’s Feature Types to Read parameter will now be linked to the value of this new THEMATIC_GROUPS published parameter.

By default, the new THEMATIC_GROUPS user parameter is not a required parameter. In other words, users do not have to choose a thematic group at runtime for the workspace to run. This behavior is ideal for this workspace, as users might not want to filter the geodatabase’s feature types by thematic group. 

If the workspace author decides users should be required to select a thematic group, the Required setting for the THEMATIC_GROUPS published user parameter can be enabled by accessing this parameter’s definition in the Parameter Manager. Open the Parameter Manager by right-clicking the User Parameters node of the Navigator window, and then choose Manage User Parameters. 

3. Run the workspace

Run the workspace by clicking the Run icon along the main Workbench toolbar. The Parameter Prompt will pop up, showing the prompt text for the newly created THEMATIC_GROUPS published parameter. Choose a thematic group, and then select OK. Click Run. 

Watch the feature caches of the various reader feature types as the workspace runs; feature caches should only appear for those reader feature types associated with the chosen thematic group. 

Feature caches of reader feature types when the Transport thematic group was selected at runtime 

Now, users can read features into the workspace by thematic group thanks to a unique choice-type published parameter.
 

Published Parameters FAQ

Can I pass a published 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 published 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 published 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.

Data Attribution

The data used throughout the above exercises originates from open data made available by the City of Vancouver, British Columbia. It contains information licensed under the Open Government License - Vancouver.