Fixed rules: More on Parameter processing

In the famous "lets do it right this time" release of Pentaho Reporting 3.5, we introduced the ability to have parameter on a report. Well, it wasn't quite right, with parameters you need to pre and post process the data to make it sound. That was release 3.6. At that point, so our theory, you, dear user, should be happy. But apparently, the beast we created wasn't all pretty.

Well, its PRD-3.7 now and guess what we are improving: Parameters.

So far, the date parameter processing was not quite right. I still wonder why after 5 years of XAction no one complained about that. Sure, XActions only have strings, and any processing or parsing is up to you - and so is the blame if it does not work.

The various system level options on the parameter UIs was .. sub-optimal. (I'm getting better at phrasing it more positively, don't you think?) The list of supported parameter (aka "the list of parameters you shall not use in your report") grew with every release. The Swing UI and the server UI never quite agreed on what setting to accept and how to behave in border cases. Thus creating formulas that worked in both settings was a chore.

And last but not least: Validating parameters and getting them run in a consistent way was difficult. Give a Integer where a Long was expected and you are screwed. Without a error message. Thus even for me working with the parameters was more a easter-egg search than sane designing.

And last but not least: Even the parameter processing order was a bit funny. It works for simple cases, but behaves rather funny for the not so simple ones.

How Pentaho Reporting Processes Parameters

Each parameter in Pentaho Reporting carries at least two formulas that eventually need to be evaluated.

The default-value-formula is used to produce a valid value if the user provided no value.

The post-processing-formula is used to transform the user's input into something more usable or simply to validate arbitrary business rules (a deposit cannot be negative, for instance).

And last but not least, if you reference an other parameter, you expect it to contain the proper post-processed value.

In PRD-3.6, the order of the validation was largely out of sync with those expectations. In fact, post processing was done in blocks, so that parameter were not able to use other post-processed parameter values in their queries. Now that's bad, and I guess Gretchen will be able to share a few unhappy tales in Lisbon about that.

In PRD-3.7, each parameter is now fully processed on its own before the next defined parameter in the chain is processed.

Lets be more formal for a while:

For each parameter defined:

If the value for the parameter is <null>, we compute the parameter's default value and use that as untrusted parameter value. The default-value formula only sees the previously validated parameters.

In a second step, we post process the parameter to get a trusted value. The post processing formula sees the previously validated parameters and the untrusted value. So be careful how you use the untrusted value here, as you cannot trust users and SQL-injections or cross-site-scripting troubles are never to far away.

If the post-processing formula fails with an error the trusted value of the parameter will be null, a warning message will be issued and last but not least we refuse to execute the report. The parameter processing continues with this value set to <null>.

And finally we check the type of the parameter and compare the parameter value against the list of valid key-values. If the value passes this test it becomes a trusted value and will be used in the further parameter processing and ultimately it will be used in the report.

If the parameter fails the test, we report an error, prevent any report processing and continue to validate the remaining parameters using the parameter's default value.

Beginning with this version, the parameter validation also creates the set of validated values after the validation is complete. For a report without any parameter values set, this will yield the default values for all parameters.

So what does this mean for you?

The new schema brings a couple of changes to the way the system behaves. Default values are now context sensitive and can change when the selection for the previously declared parameters changes. Our parameter UIs do not directly use that feature for usability reasons.Automatically changing the user's input is not very nice and confuses and/or upsets people. A lot.

The post processing formulas are now executed in a timely manor and before the default-value or selection for a parameter is computed. This way, you are now able to compute the mondrian-role array in a hidden parameter's post-processing formula and be sure that your datasource sees it.

And last but not least, your formulas wont be able to use values that have not been validated, nor would the report ever include them. Especially with the SINGLEVALUEQUERY and MULTIVALUEQUERY formula functions, this is mandatory. Your database is yours and we all want to keep it that way.