Working With Conditionally Visible Published User Parameters in FME Form

FME Version

Files

ConditionalVisibility_2023.fmwt
- 500 KB
- Download

Introduction

New for FME 2023.0, conditional visibility of workspace published parameters allows authors to decide under what condition(s) published parameters will be exposed at runtime. In this way, those published parameters which are not relevant to a particular translation may be disabled or hidden based upon the value selected for another user parameter. These published parameter dependencies can help alleviate possible translation errors associated with inputting incorrect parameter values at runtime. More information on this conditional visibility of published parameters can be found in the FME Form 2023.0+ documentation .

Prior to FME 2023.0, all published user parameters of a workspace were exposed at runtime in the Translation Parameter Values prompt. As a result, workspace authors often had to include instructions to the user on how to populate these user parameters such that desired translation results could be achieved. Authors did not have a way to hide irrelevant parameters based on the value(s) selected for other published parameters. In short, authors couldn’t readily create dependencies amongst published user parameters.

This article will walk through a simple example of how to use the Conditional Visibility property available for workspace published user parameters in FME 2023.0+.

Note: Users should be fluent in creating and managing workspace user parameters before proceeding with the example in this article. For introductory material on FME published parameters, please see the FME Community article Using the Parameter Manager and its related articles.

Step-by-Step Instructions

As the conditional visibility of published user parameters is new for FME Form 2023.0, users will need access to FME Workbench 2023.0+ to follow along with the example below.

1. Download ConditionalVisibility_2023.fmwt

Download ConditionalVisibility_2023.fmwt. Open the workspace template in FME Workbench 2023.0+, and save it locally. This workspace uses an OGC GeoPackage source dataset containing two tables:

a parks table, with polygon features of parks found in Surrey, BC; and
a trash container table with point features of trash containers found throughout Surrey, BC

Source OGC GeoPackage in Visual Preview, with park areas as green polygons and trash containers as blue points

The overall goal of this translation is to identify parks in Surrey, BC which may be under-serviced by trash containers. This objective is accomplished primarily through the conditional visibility of a user parameter group box, where users can decide between the following two translation options:

Simple overlay of trash container locations on park areas, followed by a Tester to identify those parks which do not contain the minimum acceptable number of trash containers; or
More complex analysis that filters parks by park area statistics, and then identifies parks that do not contain the minimum number of trash containers acceptable for their area.

Note: The term “park area” used throughout this example refers to the mathematical area occupied by the parks, not the geographical area that these parks fall into. To illustrate this important distinction, these parks fall within the geographical area of Surrey, BC. They occupy a mathematical area that is calculated from their individual on-the-ground boundaries and measured in square meters. It is this mathematical area that is of interest to the remainder of this example workspace.

2. Access the Manage User Parameters dialog in FME Workbench

Access the Manage User Parameters dialog in FME Workbench. This can be done in one of two ways:

Right-click on the User Parameters section of the Navigator pane, and choose Manage User Parameters

Right-click on User Parameters in the Navigator pane

Click on the Manage User Parameters toolbar button. If this button does not appear in the toolbar, it can be added from the Toolbar menu of FME Options (Tools → FME Options). In the Available Actions pane, expand the Tools group and double-click on the Manage User Parameters gear icon to add this button to the Workbench toolbar.

Access Tools → FME Options and add Manage User Parameters to the Toolbar

Once the Manage User Parameters dialog opens, select the Include Park Area Statistics group box to view its definition at right.

This group box is configured as a checkable published parameter, with its default state set to unchecked. It is used in the first workspace Tester to direct the flow of features based on whether the user wishes to consider area statistics in the downstream calculation.

Now, select the published user parameter found within this group box, and view its definition on the right.

Notice how the new Conditional Visibility option has been enabled. The If…Then…Else statement found just below the Conditional Visibility option describes the condition under which the parameter will be visible in the runtime parameter prompt. In this example workspace, this AREA_TYPE parameter will only be visible at runtime if the user chooses to enable the Include Park Area Statistics parameter. Otherwise, it will be hidden in the runtime prompt. This visibility limitation makes sense, since the AREA_TYPE parameter is only needed if users wish to filter parks by area statistics before performing further analysis.

3. Select the Set Up TestFilter Group Box

Select the Set Up TestFilter group box to view its definition.

This group box has Conditional Visibility enabled; it will be hidden unless users enable the Include Park Area Statistics parameter at runtime. The parameters within this group box are exclusively applied to the TestFilter in the workspace, which is only run when users choose to include area statistics in the workflow. So it makes sense to hide this group box in the runtime prompt until it’s needed.

To view how the Set Up TestFilter group box will look in the runtime prompt, click the Preview button at the bottom right of the Manage User Parameters dialog.

The Parameter Preview dialog opens, showing a preview of how the runtime Translation Parameter Values prompt will look when the workspace is run. By default, the Include Park Area Statistics parameter is disabled. As expected, the dependent Set Up TestFilter group is hidden.

Now select the checkbox to the left of the Include Park Area Statistics parameter in the Parameter Preview dialog.

The Set Up TestFilter group box, as well as the parameters it contains, are now visible in the Parameter Preview dialog.

Click Close at the bottom right of Parameter Preview to return to the Manage User Parameters dialog.

An important point to keep in mind about the new Conditional Visibility property is that the order of parameters in the Manage User Parameters dialog matters. More specifically, when one parameter’s visibility depends on the state or value of another parameter, the dependent parameter must reside below its related parameter in the Manage User Parameters dialog. Otherwise, the visibility condition set on the dependent parameter will no longer be valid, and its If…clause will appear red.

This parameter order concept can be readily tested in the example workspace. First, select the Set UpTestFilter group box, and expand the Conditional Visibility drop-down menu to view the If…Then…Else…statement therein.

Again, this group box’s visibility at runtime depends on the state of the Include Park Area Statistics group box that resides above it.

Now, watch the Set Up TestFilter’s If… clause as you click the Move Up icon three times. This will move the Set Up TestFilter group box to reside completely above the Include Park Area Statistics group box.

The visibility If…clause of Set Up TestFilter has been invalidated because this group box now resides above the parameter it depends upon. It’s therefore important to keep parameter order in mind as the Conditional Visibility of published user parameters is established while authoring a workspace.

Select the Set Up TestFilter group box, and then click the Move Down icon three times to revalidate this parameter’s visibility condition.

4. Select Each Parameter Within the Set Up TestFilter Group Box

Select each parameter within the Set Up TestFilter group box, one at a time, ignoring the top Message parameter.

Each of these parameters has Conditional Visibility disabled. Since these parameters reside within a group box with Conditional Visibility enabled, they will behave according to the condition set for the containing group box. They will be hidden along with the group box until the Include Park Area Statistics parameter is enabled at runtime.

If one of the parameters within the Set Up TestFilter group box requires more restrictive visibility, then the Conditional Visibility option could be used on that specific parameter to further control its visibility at runtime. In this way, multiple visibility conditions may be set for one parameter.

To view this additional visibility constraint in action, select the TESTFILTER_RIGHT_VALUE parameter from the Set Up TestFilter group box. Enable Conditional Visibility for this parameter.

Next, set the Conditional Visibility If…Then…Else… clauses to the following:

If     TESTFILTER_LEFT_VALUE   Is   sometext
Then   Show As Enabled
Else   Show As Disabled

Click the Preview button at the bottom right of Manage User Parameters, and enable Include Park Area Statistics in the Parameter Preview dialog that opens.

The right value parameter within the Set Up TestFilter parameter group is grayed out, even though the visibility condition for this parameter group has been met. The visibility condition set on this right value parameter must now be met to activate it at runtime.

Type “sometext” into the left value parameter input field.

Now the right value parameter is enabled and ready to accept user input.

Click Close on the Parameter Preview dialog to return to Manage User Parameters. Select the TESTFILTER_RIGHT_VALUE parameter, and disable Conditional Visibility to return this parameter to its original definition.

5. Select the Choose minimum acceptable number of trash cans for all parks parameter

Select the Choose minimum acceptable number of trash cans for all parks parameter, just below the Set Up TestFilter group box, to view its definition on the right. This parameter allows the workspace user to specify the minimum acceptable number of trash cans for all parks in Surrey, regardless of park area.

Note how this parameter does not have Conditional Visibility enabled, and will therefore always appear active in the runtime parameter prompt. Test this out by clicking on the Preview button in Manage User Parameters. Now alternately enable and disable the Include Park Area Statistics parameter while watching the Choose minimum acceptable number of trash cans for all parks parameter.

With Include Park Area Statistics disabled

With Include Park Area Statistics enabled

This is not desirable behavior, as this parameter is not relevant at all times during translation. It is only needed when the user leaves the Include Park Area Statistics parameter disabled at runtime. To prevent workspace users from inputting values into this parameter unnecessarily, it should be hidden until required.

To adjust this parameter’s visibility, close the Parameter Preview dialog and return to Manager User Parameters.

Next, select the Choose minimum acceptable number of trash cans for all parks parameter, and enable its Conditional Visibility option.

Complete the visibility If…Then…Else…statement as follows:

If     INCLUDE_STATS   Is   <checked>
Then   Hide
Else   Show As Enabled

Now, select the Preview button to return to the Parameter Preview dialog once more. Test out the adjusted visibility of this parameter by enabling and disabling Include Park Area Statistics.

Conditional Visibility enabled and Include Park Area Statistics disabled

Conditional Visibility enabled and Include Park Area Statistics enabled

The Choose minimum acceptable number of trash cans for all parks parameter is now hidden when Include Park Area Statistics is enabled.

Click Close on the Parameter Preview dialog to return to Manage User Parameters.

6. Select Each Destination CSV folder Parameter

Select each Destination CSV folder parameter to view its definition. Each of these two parameters has Conditional Visibility enabled, but with slightly differing If…Then…Else statements.

Destination CSV folder parameter - area included

Destination CSV folder parameter - all parks included

The first Destination CSV folder parameter will only be enabled if Include Park Area Statistics is enabled. This makes sense, as this parameter is only applied to the CSV writer capturing the area-filtered calculation.

The second Destination CSV folder parameter is only applied to the CSV writer that captures all parks, regardless of park area. Accordingly, this parameter will only be enabled if Include Park Area Statistics is disabled. Both of these parameters will show as disabled (grayed out) when their visibility condition is not met.

Destination CSV folder parameters with Include Park Area Statistics disabled

Destination CSV folder parameters with Include Park Area Statistics enabled

The user parameters for this workspace are now ready to be tested. Click Close at bottom right of the Parameter Preview dialog. Click OK at the bottom right of the Manage User Parameters dialog to return to the workspace canvas.

7. Enable Prompt for Parameters and Run the Workspace

Enable Prompt for Parameters in the Run drop-down menu, and then run the workspace.

The Translation Parameter Values dialog will open, prompting the user to input values for the various published user parameters. The parameters visible to the user will change based upon the state of the Include Park Area Statistics parameter.

Runtime Prompt for Parameters - Include Park Area Statistics disabled

Runtime Prompt for Parameters - Include Park Area Statistics enabled

Now, users will only be able to provide values to the published parameters required for their specific translation, while extraneous parameters are no longer available in the runtime prompt. The conditional visibility of published user parameters has been successfully implemented in this workspace.

Additional Information

FME Form 2023 Documentation:

FME Community Knowledge Base Articles:

Data Attribution

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

Working With Conditionally Visible Published User Parameters in FME Form

FME Version

Files

Introduction

Step-by-Step Instructions

Additional Information

Data Attribution

Was this article helpful?

Comments

Search

Working With Conditionally Visible Published User Parameters in FME Form

FME Version

Files

Introduction

Step-by-Step Instructions

Additional Information

Data Attribution

Was this article helpful?

Comments