Combining User Parameters

Introduction

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.

The following exercise demonstrates how to use a user parameter with the WHERE clause of an Esri Geodatabase (OpenFile Geodb) 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.

The source data and workspace template can be downloaded from the Files section

Step-by-Step Instructions

1. Open Starting Workspace

Download CombiningUserParameters_START_2026_3.fmwt from the Files section and open the workspace in FME Workbench. 

The source data consists of Vancouver bike path line segments, with a WHERE clause specified on its reader feature type (WHERE “PathName” = ‘Ontario’)

In its current state, this workspace will read all line segments stored in the BikePathSegments feature class of the source file geodatabase. We will create a user 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 extra data into the workspace. 

Either save the workspace locally to access the source dataset, or download the SourceData from the Files section as we will be referencing the folder in this tutorial.

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 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 bike path line segments where the PathName attribute value is ‘Ontario’. 

The goal is to give users the ability to choose the value for PathName at runtime, so this WHERE clause needs a user parameter applied to it. 

3. Add a Choice User Parameter

Right-click on the User Parameters node in the Navigator window and select Manage User Parameters. In the Parameter Manager dialog that opens, click the green plus icon in the top left and choose the Choice option from the drop-down menu.

A new user parameter will appear in the left-side of the Parameter Manager and its default definition will appear in the right-side display. If the newly added Choice parameter is not already highlighted at the left, select it and then rearrange the item to be placed under the File Geodatabase parameter. Items can be shuffled around using the Move Up and Move Down buttons in the Toolbar or by dragging the item with your mouse.

The order in which user 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. Since the File Geodatabase parameter and the newChoice  parameter are both related to the reader, and the reader is actioned first in the workspace, having these two user parameters appear first and second in the Parameter Prompt makes the most sense.

The remaining user parameters can be repositioned similarly. Once reordering is finished, the list of user 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 user user parameters will look in the runtime Parameter Prompt.

4. Define the Choice User Parameter

Select the Choice user parameter in the Parameter Manager, and configure the parameter definition as follows: 

• Parameter Identifier: PATHNAMES
• Label: Choose bike path(s) to read into the workspace, by path name
• Required: Enabled
• Show Label: Enabled
• Visibility: Always Show
• Choice Configuration: List

In the Choices list under Choice Configuration, 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.

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 the 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. In the Select Source Dataset dialog, set the following parameters:

• Format: Esri Geodatabase (OpenFile Geodb)
• Dataset: /VancouverOpenData.gdb
  • Browse to downloaded source data or locally saved workspace folder

Click Continue in the Import Wizard. In the Specify Import Mode and Select Feature Types dialog, set the following parameters:

• Import From: Attribute Values
• Feature Types: BikePathSegments
  • Select from the list of tables

Click Continue. In the Select Attributes dialog, configure the following:

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

Click Import. This action will return the display to the Parameter Manager. Notice how the Value and Display options in the Choices table of the new user parameter have been populated with the values of the selected PathName attribute.

In this case, we need the path names to have single quotations surrounding the value so we can apply the SQL WHERE clause. Click into each name under the Value column to add single quotes to the path name. For example, Burrard should become ‘Burrard’.

Under the Choice Configuration heading, set the following parameters:

• Allow Multiple Selection: Enabled
  • This allows users choose one or many bike path names at runtime
• Advanced:
  • Choice List Delimiter: Comma

This 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 user 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.

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

The new Choice user parameter appears in the Parameter Prompt, just below the File Geodatabase parameter. Click the ellipsis to the right of the Choice parameter to view the configured 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 '

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 parameter and return to the canvas. 

The new PATHNAMES user parameter will appear under the User Parameter node of the Navigator window.

5. Apply the Choice User Parameter

We will apply the Choice user parameter we just created to the WHERE clause of the File Geodatabase reader. 

Double-click on the BikePathSegments reader feature type on the canvas to open the Feature Type parameters dialog.

Currently, the WHERE clause restricts the reader to reading only those bike path segments whose PathName value equals ‘Ontario’. We will adjust the WHERE clause to make use of the new Choice user parameter.

Click the ellipsis to the right of the WHERE Clause.

The WHERE Clause dialog will open. Delete the existing WHERE clause and replace it with the following:

"PathName" IN ($(PATHNAMES))

Now, the WHERE clause is referencing the value of the new Choice user parameter by including $(PATHNAMES). The WHERE clause will also accommodate multiple bike path name selections with the use of the IN operator.

Click OK twice to return to the main canvas.

6. Run Workspace

With Prompt for Parameters enabled, click the Run button in the Toolbar. In the Translation Parameter Values dialog, ensure the File Geodatabase parameter is pointing to VancouverOpenData.gdb. Choose at least two path name options for the list choice parameter. 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.

• File Geodatabase: /VancouverOpenData.gdb
• Choose bike path(s) to read into the workspace, by path name: Adanac,Burrard,Cypress
  • Click the ellipsis to select the bike paths 
• Do you want to calculate bike path statistics (CSV output)?: Enabled
• Specify the destination folder for outputs: /Output
• Enter a file name for the MITAB output: JoinedBikePaths
• Enter a file name for the CSV output: BikePathStats
• Save AS Parameter Default Values: Disabled 

Click 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.

With this Choice user 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.

Additional Resources

User Parameters in FME Form [Article]

FME and SQL: A Dynamic Duo for Data Integration [Article]

Creating and Modifying User Parameters [Documentation]

Data Attribution

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