Question of the Week: Choice with Alias Parameters Run Programmatically

Seasons greetings, FMEers.

Our main question this week comes from our support queue and relates to published parameters used programmatically.

Note: I have an up-to-date list of previous Question of the Week topics in case it's of interest to you.

Question of the Week

Q) The behavior of choice with alias parameters on FME Server does not seem to be working as expected when called programmatically. Values are taken literally and not converted. Can you please confirm how it should work?

A) Of course. It might seem odd, but I believe this is actually working as designed. The difference is in running a workspace through FME (Desktop or Server) and running it programmatically. Let's see why...

Choice with Alias Parameters

Here's a quick refresher on user parameters in general and the Choice with Alias type in particular.

A User Parameter is a way to get input from a user when they run a workspace. They are sometimes also called Published Parameters, since you publish them to get user input, or keep them private for your own use.

User parameters come in many styles, for different types of input. A Choice with Alias type of parameter is where we present the user with a list of options, but return a different value to FME. Let's look at an example. Here our accounting department has a Choice with Alias:

Later there is an SQLExecutor transformer that gives the chosen user a 50% pay rise:

UPDATE employees SET salary = salary * 1.5 where employeeID = "$(Employee)"

If I run this in FME Desktop (left) or FME Server (right), it looks like this:

The important part is that the user gets to select an employee name, but the value passed to the SQL statement is the employee ID number, which is what the database expects.

But what if I run this programmatically?

Running a Workspace Programmatically

What do I mean by programmatically? Well, I mean, not using an FME user interface. For example, when I do run it in Workbench I'm told what the command would be to run this in a script:

Using that command in a bat file (for example) would mean running the workspace programmatically.

Be sure to notice that the user parameter value it suggests you submit with the workspace has already had its alias replaced with the true value.

Let's see if the same is true in Server:

Yes, when I create a webhook to run the workspace the same substitution has already taken place.

In short, it's not the FME engine that carries out the switch, but the tool that initiates it. 

Or at least, that's what it seems to me. So when I create a tool for running a workspace programmatically, it's expected that I'm responsible for presenting published parameters to the user, including any aliases I might care to apply.

Why is this the expected method? Well, I haven't checked with our developers so I can only guess. But the whole Choice with Alias parameter comes about because we want to be able to show a complex string to the user but deliver a simple string to the FME engine.

For example, if I were creating a parameter to let the user decide on the choice of a coordinate system:

...would I really want to pass a value like "Ontario MTM Zone 12,82.5-79.5W over47N, 82.5-80.25W toS; NAD83 [EPSG #32192]" though a URL or command line?

But, as a developer, is there any way I can make use of these aliases programmatically?

Listing and Validating Values

We now know that the FME engine won't substitute an alias for our choice and (presumably) validation of other parameters is done the same way. For example, if a Number parameter is defined in a workspace, validation that the input is actually a number (not text) must also be done by the interface, not the engine.

So if I'm creating a web-based solution to run a workspace, maybe I'm not the same person as the workspace author. Maybe I know the parameter name but I have no idea what sort of input is permitted. Or perhaps the workspace was edited without me even knowing about it!

Is there a way to query FME to find out what values I should present to the user?

Why, yes! The REST API repositories method:

Now I know. I make the call and in return get a formatted list of permitted parameter values.

But what happens if I mess up and pass through the choice instead of the alias (or another non-conforming value)? Then the value will be used literally. In my example the SQLExecutor will try to run:

UPDATE employees SET salary = salary * 1.5 where employeeID = "Mark Ireland"

So what would happen there?

If the employee ID was purely numeric, then a text value would probably cause the SQL itself to fail. If the employee ID was text then the SQL will run but return zero records.

Hopefully there would be some other test in the workspace to error trap such a case - otherwise I won't be getting my salary increase!

Note: This is why I always emphasize the need to trap potential errors in a workspace. You might think that everything is all under control, but only error trapping assures that. Test your inputs and connect those Rejected ports to something, folks!

So there we go. That's how a Choice with Alias parameter works when running a workspace programmatically. I hadn't thought about it until the question was raised, but it is logical.

The key is that FME engines don't validate user input. User input should be validated by the program submitting the request.

If you want to know more about how to dynamically generate a form showing user parameters, check out this section of the FME Server API training course.

Other Notable Questions

Some other notable questions this week are...

• When and how to use Attribute Management Transformers for Performance Tuning
  • @bwn asks this question and it is interesting to wonder if the time taken to remove attributes exceeds the time gained in performance. But what is most interesting is when @markatsafe (as opposed to me, @mark2atsafe) reports how the AttributeKeeper is not bulk-mode compliant (yet) and so can impact performance.
• Time Conversion from Local to UTC (and Vice Versa)
  • Not so much a question as a tip from @egge - the @TimeZoneSet function is very handy and doesn't have an equivalent transformer, so it's not as well known.
    • Incidentally, all users, please feel free to post tips like this to the forums. I know they are very much appreciated by all.
• Comparing Dates in FME
  • A good question from @muhammad_yasir about how to compare dates in the Tester. What's particularly interesting is that the dates appear to be YYYYmm only, and exclude the day. But beyond that, it's a reminder to always set the comparison mode to Date/Time in the Tester when necessary.
• Calculating Multiple Attributes using the ExpressionEvalautor
  • Another good question from @muhammad_yasir. The point to note is that if you have a bunch of different calculations to carry out, then the ExpressionEvalautor is not the transformer to use. Use an AttributeManager, AttributeCreator, or similar.
  • On the other hand, if you have a bunch of attributes that need the same calculation carried out, then the ExpressionEvalautor is the one to use. You replace the attribute name with @CurrentAttribute() in the expression, and FME works through each attribute one at a time.
• Turning Off Feature Caching for a Workspace
  • We know how to turn off feature caching, but does the end-user, asks @virtualcitymatt. It's a good point. Currently, we would say to use the Quick Translator, but perhaps the ideas linked to in the question will help?